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] > select * from (values(4,5,6),(7,8,9)) as t;
-+---+---+---+
-| 4 | 5 | 6 |
-+---+---+---+
-| 4 | 5 | 6 |
-| 7 | 8 | 9 |
-+---+---+---+
-[localhost:21000] > 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>
