IMPALA-8855: [DOCS] Document the generic VALUES clause

- Added a paragraph on implicit conversion in impala_datatypes.xml

Change-Id: I2568450993323236535a8f1d022dee7d09ecf62b
Reviewed-on: http://gerrit.cloudera.org:8080/14661
Tested-by: Impala Public Jenkins <impala-public-jenkins@cloudera.com>
Reviewed-by: Tim Armstrong <tarmstrong@cloudera.com>
diff --git a/docs/impala.ditamap b/docs/impala.ditamap
index 8e11b89..ec8e03a 100644
--- a/docs/impala.ditamap
+++ b/docs/impala.ditamap
@@ -258,6 +258,7 @@
       <topicref href="topics/impala_update.xml"/>
       <topicref href="topics/impala_upsert.xml"/>
       <topicref href="topics/impala_use.xml"/>
+      <topicref href="topics/impala_values.xml"/>
       <topicref href="topics/impala_hints.xml"/>
     </topicref>
     <topicref href="topics/impala_functions.xml">
diff --git a/docs/topics/impala_datatypes.xml b/docs/topics/impala_datatypes.xml
index 8076df6..a1bfe18 100644
--- a/docs/topics/impala_datatypes.xml
+++ b/docs/topics/impala_datatypes.xml
@@ -34,28 +34,37 @@
   </prolog>
 
   <conbody>
-
-    <p>
-      <indexterm audience="hidden">data types</indexterm>
-      Impala supports a set of data types that you can use for table columns, expression values, and function
-      arguments and return values.
-    </p>
-
-    <note>
-      Currently, Impala supports only scalar types, not composite or nested types. Accessing a table containing any
-      columns with unsupported types causes an error.
-    </note>
-
+    <p>Impala supports a set of data types that you can use for table columns,
+      expression values, and function arguments and return values. </p>
+    <note> Currently, Impala supports only scalar types, not composite or nested
+      types. Accessing a table containing any columns with unsupported types
+      causes an error. </note>
     <p outputclass="toc"/>
-
-    <p>
-      For the notation to write literals of each of these data types, see
-      <xref href="impala_literals.xml#literals"/>.
-    </p>
-
-    <p>
-      See <xref href="impala_langref_unsupported.xml#langref_hiveql_delta"/> for differences between Impala and
-      Hive data types.
-    </p>
+    <p> For the notation to write literals of each of these data types, see
+        <xref href="impala_literals.xml#literals"/>. </p>
+    
+      <p> Impala supports a limited set of implicit casts to avoid undesired
+      results from unexpected casting behavior. </p>
+    <ul>
+      <li> Impala does not implicitly cast between string and numeric or Boolean
+        types. Always use <codeph>CAST()</codeph> for these conversions. </li>
+      <li> Impala does perform implicit casts among the numeric types, when
+        going from a smaller or less precise type to a larger or more precise
+        one. For example, Impala will implicitly convert a
+          <codeph>SMALLINT</codeph> to a <codeph>BIGINT</codeph> or
+          <codeph>FLOAT</codeph>, but to convert from <codeph>DOUBLE</codeph> to
+          <codeph>FLOAT</codeph> or <codeph>INT</codeph> to
+          <codeph>TINYINT</codeph> requires a call to <codeph>CAST()</codeph> in
+        the query. </li>
+      <li> Impala does perform implicit casts from <codeph>STRING</codeph> to
+          <codeph>TIMESTAMP</codeph>. Impala has a restricted set of literal
+        formats for the <codeph>TIMESTAMP</codeph> data type and the
+          <codeph>FROM_UNIXTIME()</codeph> format string; see <xref
+          href="impala_timestamp.xml#timestamp"/> for details. </li>
+    </ul>
+    <p>See the topics under this section for full details on implicit and
+      explicit casting for each data type, and see <xref
+        href="impala_conversion_functions.xml#conversion_functions"/> for
+      details about the <codeph>CAST()</codeph> function.</p>
   </conbody>
 </concept>
diff --git a/docs/topics/impala_insert.xml b/docs/topics/impala_insert.xml
index 58b5169..c1db6d5 100644
--- a/docs/topics/impala_insert.xml
+++ b/docs/topics/impala_insert.xml
@@ -504,41 +504,6 @@
         <codeph>NULL</codeph>.
       </p>
 
-<!--
-      <p>
-        does not support specifying a subset of the
-        columns in the table or specifying the columns in a different order. Use a
-        <codeph>VALUES</codeph> clause with all the column values in the same order as
-        the table definition, using <codeph>NULL</codeph> values for any columns you
-        want to omit from the <codeph>INSERT</codeph> operation.
-      </p>
--->
-
-      <p>
-        To use a <codeph>VALUES</codeph> clause like a table in other statements, wrap it in parentheses and use
-        <codeph>AS</codeph> clauses to specify aliases for the entire object and any columns you need to refer to:
-      </p>
-
-<codeblock>[localhost:21000] &gt; select * from (values(4,5,6),(7,8,9)) as t;
-+---+---+---+
-| 4 | 5 | 6 |
-+---+---+---+
-| 4 | 5 | 6 |
-| 7 | 8 | 9 |
-+---+---+---+
-[localhost:21000] &gt; select * from (values(1 as c1, true as c2, 'abc' as c3),(100,false,'xyz')) as t;
-+-----+-------+-----+
-| c1  | c2    | c3  |
-+-----+-------+-----+
-| 1   | true  | abc |
-| 100 | false | xyz |
-+-----+-------+-----+</codeblock>
-
-      <p>
-        For example, you might use a tiny table constructed like this from constant literals or function return
-        values as part of a longer statement involving joins or <codeph>UNION ALL</codeph>.
-      </p>
-
       <p conref="../shared/impala_common.xml#common/hdfs_blurb"/>
 
       <p>
diff --git a/docs/topics/impala_langref_unsupported.xml b/docs/topics/impala_langref_unsupported.xml
index 9746827..af81a90 100644
--- a/docs/topics/impala_langref_unsupported.xml
+++ b/docs/topics/impala_langref_unsupported.xml
@@ -260,34 +260,29 @@
       </p>
 
       <ul>
-        <li>
-          Impala supports a limited set of implicit casts. This can help avoid undesired results from unexpected
-          casting behavior.
-          <ul>
-            <li>
-              Impala does not implicitly cast between string and numeric or Boolean types. Always use
-              <codeph>CAST()</codeph> for these conversions.
-            </li>
-
-            <li>
-              Impala does perform implicit casts among the numeric types, when going from a smaller or less precise
-              type to a larger or more precise one. For example, Impala will implicitly convert a
-              <codeph>SMALLINT</codeph> to a <codeph>BIGINT</codeph> or <codeph>FLOAT</codeph>, but to convert from
-              <codeph>DOUBLE</codeph> to <codeph>FLOAT</codeph> or <codeph>INT</codeph> to <codeph>TINYINT</codeph>
-              requires a call to <codeph>CAST()</codeph> in the query.
-            </li>
-
-            <li>
-              Impala does perform implicit casts from string to timestamp. Impala has a restricted set of literal
-              formats for the <codeph>TIMESTAMP</codeph> data type and the <codeph>from_unixtime()</codeph> format
-              string; see <xref href="impala_timestamp.xml#timestamp"/> for details.
-            </li>
-          </ul>
-          <p>
-            See <xref href="impala_datatypes.xml#datatypes"/> for full details on implicit and explicit casting for
-            all types, and <xref href="impala_conversion_functions.xml#conversion_functions"/> for details about
-            the <codeph>CAST()</codeph> function.
-          </p>
+        <li> Impala supports a limited set of implicit casts. This can help
+          avoid undesired results from unexpected casting behavior. <ul>
+            <li> Impala does not implicitly cast between string and numeric or
+              Boolean types. Always use <codeph>CAST()</codeph> for these
+              conversions. </li>
+            <li> Impala does perform implicit casts among the numeric types,
+              when going from a smaller or less precise type to a larger or more
+              precise one. For example, Impala will implicitly convert a
+                <codeph>SMALLINT</codeph> to a <codeph>BIGINT</codeph> or
+                <codeph>FLOAT</codeph>, but to convert from
+                <codeph>DOUBLE</codeph> to <codeph>FLOAT</codeph> or
+                <codeph>INT</codeph> to <codeph>TINYINT</codeph> requires a call
+              to <codeph>CAST()</codeph> in the query. </li>
+            <li> Impala does perform implicit casts from string to timestamp.
+              Impala has a restricted set of literal formats for the
+                <codeph>TIMESTAMP</codeph> data type and the
+                <codeph>from_unixtime()</codeph> format string; see <xref
+                href="impala_timestamp.xml#timestamp"/> for details. </li>
+          </ul><p> See the topics under <xref
+              href="impala_datatypes.xml#datatypes"/> for full details on
+            implicit and explicit casting for each data type, and <xref
+              href="impala_conversion_functions.xml#conversion_functions"/> for
+            details about the <codeph>CAST()</codeph> function. </p>
         </li>
 
         <li>
diff --git a/docs/topics/impala_values.xml b/docs/topics/impala_values.xml
new file mode 100644
index 0000000..a32f1c1
--- /dev/null
+++ b/docs/topics/impala_values.xml
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="values">
+
+  <title>VALUES Statement</title>
+  <titlealts audience="PDF"><navtitle>VALUES</navtitle></titlealts>
+  <prolog>
+    <metadata>
+      <data name="Category" value="Impala"/>
+      <data name="Category" value="SQL"/>
+      <data name="Category" value="Developers"/>
+      <data name="Category" value="Data Analysts"/>
+    </metadata>
+  </prolog>
+
+  <conbody>
+    <p> In addition to being part of the <codeph>INSERT</codeph> statement, the
+        <codeph>VALUES</codeph> clause can be used as stand-alone statement or
+      with the <codeph>SELECT</codeph> statement to construct a data set without
+      creating a table. For example, the following statement returns a data set
+      of 2 rows and 3 columns.
+      <codeblock>
+VALUES ('r1_c1', 'r1_c2', 'r1_c3')
+     , ('r2_c1', 'r2_c2', 'r2_c3');</codeblock></p>
+    <p><b>Syntax:</b></p>
+    <codeblock>VALUES (<varname>row</varname>)[, (<varname>row</varname>), ...];
+
+SELECT <varname>select_list</varname> FROM (VALUES (<varname>row</varname>)[, (<varname>row</varname>), ...]) AS <varname>alias</varname>;
+
+<varname>row</varname> ::= <varname>column</varname> [[AS <varname>alias</varname>], <varname>column</varname> [AS <varname>alias</varname>], ...]</codeblock>
+    <ul>
+      <li>The <codeph>VALUES</codeph> keyword is followed by a comma separated
+        list of one or more <varname>row</varname>s.</li>
+      <li><varname>row</varname> is a comma-separated list of one or more
+          <varname>column</varname>s.</li>
+      <li>Each <varname>row</varname> must have the same number of
+          <varname>column</varname>s.</li>
+      <li><varname>column</varname> can be a constant, a variable, or an
+        expression.</li>
+      <li>The corresponding <varname>column</varname>s must have compatible data
+        types in all <varname>row</varname>s. See the third query in the
+        Examples section below.</li>
+      <li>By default, the first row is used to name columns.  But using the
+          <codeph>AS</codeph> keyword, you can optionally give the column an
+          <varname>alias</varname>. </li>
+      <li>If used in the <codeph>SELECT</codeph> statement, the
+          <codeph>AS</codeph> keyword with an <varname>alias</varname> is
+        required.</li>
+      <li>
+        <varname>select_list</varname> is the columns to be selected for the
+        result set.</li>
+    </ul>
+    <p><b>Examples:</b></p>
+    <p>
+      <codeblock>> SELECT * FROM (VALUES(4,5,6),(7,8,9)) AS t;
++---+---+---+
+| 4 | 5 | 6 |
++---+---+---+
+| 4 | 5 | 6 |
+| 7 | 8 | 9 |
++---+---+---+
+
+> SELECT * FROM (VALUES(1 AS c1, true AS c2, 'abc' AS c3),(100,false,'xyz')) AS t;
++-----+-------+-----+
+| c1  | c2    | c3  |
++-----+-------+-----+
+| 1   | true  | abc |
+| 100 | false | xyz |
++-----+-------+-----+
+
+> VALUES (CAST('2019-01-01' AS TIMESTAMP)), ('2019-02-02');
++---------------------------------+
+| cast('2019-01-01' as timestamp) |
++---------------------------------+
+| 2019-01-01 00:00:00             |
+| 2019-02-02 00:00:00             |
++---------------------------------+</codeblock>
+    </p>
+    <p><b>Related information:</b></p>
+    <p>
+      <xref href="impala_select.xml#select"/></p>
+  </conbody>
+</concept>