You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@impala.apache.org by mi...@apache.org on 2018/10/11 19:54:06 UTC
[01/10] impala git commit: IMPALA-7680: [DOCS] Minor edits to the
command line config section
Repository: impala
Updated Branches:
refs/heads/master 8ca79261a -> 004719126
IMPALA-7680: [DOCS] Minor edits to the command line config section
Change-Id: I3a3115feb2de1112ff0d2687a83a1307bd0791a5
Reviewed-on: http://gerrit.cloudera.org:8080/11636
Tested-by: Impala Public Jenkins <im...@cloudera.com>
Reviewed-by: Bikramjeet Vig <bi...@cloudera.com>
Project: http://git-wip-us.apache.org/repos/asf/impala/repo
Commit: http://git-wip-us.apache.org/repos/asf/impala/commit/b0d0d739
Tree: http://git-wip-us.apache.org/repos/asf/impala/tree/b0d0d739
Diff: http://git-wip-us.apache.org/repos/asf/impala/diff/b0d0d739
Branch: refs/heads/master
Commit: b0d0d73938b1fe06ea836533babad8d0c2f4bc53
Parents: 8ca7926
Author: Alex Rodoni <ar...@cloudera.com>
Authored: Tue Oct 9 15:54:40 2018 -0700
Committer: Alex Rodoni <ar...@cloudera.com>
Committed: Wed Oct 10 18:06:10 2018 +0000
----------------------------------------------------------------------
docs/topics/impala_admission.xml | 62 +++++++++++++++++++----------------
1 file changed, 33 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/impala/blob/b0d0d739/docs/topics/impala_admission.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_admission.xml b/docs/topics/impala_admission.xml
index 317fa80..8b114eb 100644
--- a/docs/topics/impala_admission.xml
+++ b/docs/topics/impala_admission.xml
@@ -579,27 +579,30 @@ under the License.
and <filepath>llama-site.xml</filepath> configuration files.
</p>
- <p>
- For an advanced configuration with multiple resource pools using different settings, set up the
- <filepath>fair-scheduler.xml</filepath> and <filepath>llama-site.xml</filepath> configuration files
- manually. Provide the paths to each one using the <cmdname>impalad</cmdname> command-line options,
- <codeph>--fair_scheduler_allocation_path</codeph> and <codeph>--llama_site_path</codeph> respectively.
- </p>
-
- <p>
- The Impala admission control feature only uses the Fair Scheduler configuration settings to determine how
- to map users and groups to different resource pools. For example, you might set up different resource
- pools with separate memory limits, and maximum number of concurrent and queued queries, for different
- categories of users within your organization. For details about all the Fair Scheduler configuration
- settings, see the
- <xref href="http://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-site/FairScheduler.html#Configuration" scope="external" format="html">Apache
- wiki</xref>.
- </p>
-
- <p>
- The Impala admission control feature only uses a small subset of possible settings from the
- <filepath>llama-site.xml</filepath> configuration file:
- </p>
+ <p> For an advanced configuration with multiple resource pools using
+ different settings:<ol>
+ <li>Set up the <filepath>fair-scheduler.xml</filepath> and
+ <filepath>llama-site.xml</filepath> configuration files
+ manually.</li>
+ <li>Provide the paths to each one using the
+ <cmdname>impalad</cmdname> command-line options,
+ <codeph>--fair_scheduler_allocation_path</codeph> and
+ <codeph>--llama_site_path</codeph> respectively. </li>
+ </ol></p>
+
+ <p> The Impala admission control feature uses the Fair Scheduler
+ configuration settings to determine how to map users and groups to
+ different resource pools. For example, you might set up different
+ resource pools with separate memory limits, and maximum number of
+ concurrent and queued queries, for different categories of users
+ within your organization. For details about all the Fair Scheduler
+ configuration settings, see the <xref
+ href="http://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-site/FairScheduler.html#Configuration"
+ scope="external" format="html">Apache wiki</xref>. </p>
+
+ <p> The Impala admission control feature uses a small subset of possible
+ settings from the <filepath>llama-site.xml</filepath> configuration
+ file: </p>
<codeblock>llama.am.throttling.maximum.placed.reservations.<varname>queue_name</varname>
llama.am.throttling.maximum.queued.reservations.<varname>queue_name</varname>
@@ -607,16 +610,17 @@ llama.am.throttling.maximum.queued.reservations.<varname>queue_name</varname>
impala.admission-control.pool-queue-timeout-ms.<varname>queue_name</varname></ph>
</codeblock>
- <p rev="2.5.0 IMPALA-2538">
- The <codeph>impala.admission-control.pool-queue-timeout-ms</codeph>
- setting specifies the timeout value for this pool, in milliseconds.
- The<codeph>impala.admission-control.pool-default-query-options</codeph>
+ <p rev="2.5.0 IMPALA-2538"> The
+ <codeph>impala.admission-control.pool-queue-timeout-ms</codeph>
+ setting specifies the timeout value for this pool in milliseconds. </p>
+ <p rev="2.5.0 IMPALA-2538"
+ >The<codeph>impala.admission-control.pool-default-query-options</codeph>
settings designates the default query options for all queries that run
in this pool. Its argument value is a comma-delimited string of
- 'key=value' pairs, for example,<codeph>'key1=val1,key2=val2'</codeph>.
- For example, this is where you might set a default memory limit
- for all queries in the pool, using an argument such as <codeph>MEM_LIMIT=5G</codeph>.
- </p>
+ 'key=value' pairs, <codeph>'key1=val1,key2=val2, ...'</codeph>. For
+ example, this is where you might set a default memory limit for all
+ queries in the pool, using an argument such as
+ <codeph>MEM_LIMIT=5G</codeph>. </p>
<p rev="2.5.0 IMPALA-2538">
The <codeph>impala.admission-control.*</codeph> configuration settings are available in
[10/10] impala git commit: IMPALA-7693: stress test: fix Query().name
Posted by mi...@apache.org.
IMPALA-7693: stress test: fix Query().name
In the refactor as part of IMPALA-7460, loading of TPC queries no longer
returned query names (i.e., Q37). The name's presence doesn't change the
behavior of the stress test, but it does lead to nicer debuggable and
reable things, like log messages, profiles, result hashes, and runtime
info.
- Change load_tpc_queries() to return a dictionary, not a list.
- Set the .name attribute.
- Enhance the unit test to at least ensure load_tpc_queries() does not
regress again.
Testing, in addition to passing test above:
- Ran stress test and performed binary search. Made sure query names
were present in logging, runtime info, result hashes, and profiles.
Change-Id: Ie8c40beababf4c122dc8fed6c0544ee37871b9b2
Reviewed-on: http://gerrit.cloudera.org:8080/11651
Reviewed-by: Impala Public Jenkins <im...@cloudera.com>
Tested-by: Michael Brown <mi...@cloudera.com>
Project: http://git-wip-us.apache.org/repos/asf/impala/repo
Commit: http://git-wip-us.apache.org/repos/asf/impala/commit/00471912
Tree: http://git-wip-us.apache.org/repos/asf/impala/tree/00471912
Diff: http://git-wip-us.apache.org/repos/asf/impala/diff/00471912
Branch: refs/heads/master
Commit: 0047191262d6a90eb704dff880efe6e625b805bc
Parents: 0cbe37a
Author: Michael Brown <mi...@cloudera.com>
Authored: Wed Oct 10 14:34:29 2018 -0700
Committer: Michael Brown <mi...@cloudera.com>
Committed: Thu Oct 11 16:43:14 2018 +0000
----------------------------------------------------------------------
tests/infra/test_stress_infra.py | 5 ++++-
tests/stress/concurrent_select.py | 5 +++--
tests/util/test_file_parser.py | 5 +++--
3 files changed, 10 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/impala/blob/00471912/tests/infra/test_stress_infra.py
----------------------------------------------------------------------
diff --git a/tests/infra/test_stress_infra.py b/tests/infra/test_stress_infra.py
index 7e97ffa..cd9fd46 100644
--- a/tests/infra/test_stress_infra.py
+++ b/tests/infra/test_stress_infra.py
@@ -55,4 +55,7 @@ class TestStressInfra(ImpalaTestSuite):
Test that the stress test will properly load TPC workloads.
"""
workload, count = count_map
- assert count == len(load_tpc_queries(workload))
+ queries = load_tpc_queries(workload)
+ assert count == len(queries)
+ for name in queries:
+ assert name.startswith('q')
http://git-wip-us.apache.org/repos/asf/impala/blob/00471912/tests/stress/concurrent_select.py
----------------------------------------------------------------------
diff --git a/tests/stress/concurrent_select.py b/tests/stress/concurrent_select.py
index 844c245..688cdd4 100755
--- a/tests/stress/concurrent_select.py
+++ b/tests/stress/concurrent_select.py
@@ -1307,9 +1307,10 @@ def load_tpc_queries(workload):
"""Returns a list of TPC queries. 'workload' should either be 'tpch' or 'tpcds'."""
LOG.info("Loading %s queries", workload)
queries = []
- for query_text in test_file_parser.load_tpc_queries(workload):
+ for query_name, query_sql in test_file_parser.load_tpc_queries(workload).iteritems():
query = Query()
- query.sql = query_text
+ query.name = query_name
+ query.sql = query_sql
queries.append(query)
return queries
http://git-wip-us.apache.org/repos/asf/impala/blob/00471912/tests/util/test_file_parser.py
----------------------------------------------------------------------
diff --git a/tests/util/test_file_parser.py b/tests/util/test_file_parser.py
index ccd0af5..3b935d5 100644
--- a/tests/util/test_file_parser.py
+++ b/tests/util/test_file_parser.py
@@ -320,7 +320,7 @@ def write_test_file(test_file_name, test_file_sections, encoding=None):
def load_tpc_queries(workload):
"""Returns a list of TPC queries. 'workload' should either be 'tpch' or 'tpcds'."""
LOG.info("Loading %s queries", workload)
- queries = list()
+ queries = dict()
query_dir = os.path.join(
os.environ['IMPALA_HOME'], "testdata", "workloads", workload, "queries")
# IMPALA-6715 and others from the past: This pattern enforces the queries we actually
@@ -331,6 +331,7 @@ def load_tpc_queries(workload):
match = file_name_pattern.search(query_file)
if not match:
continue
+ query_name = match.group(1)
file_path = os.path.join(query_dir, query_file)
test_cases = parse_query_test_file(file_path)
file_queries = list()
@@ -341,5 +342,5 @@ def load_tpc_queries(workload):
raise Exception(
"Expected exactly 1 query to be in file %s but got %s"
% (file_path, len(file_queries)))
- queries.append(file_queries[0])
+ queries[query_name] = file_queries[0]
return queries
[05/10] impala git commit: [DOCS] Built-in Functions doc format
Changes
Posted by mi...@apache.org.
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_datetime_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_datetime_functions.xml b/docs/topics/impala_datetime_functions.xml
index da52cc8..02d2771 100644
--- a/docs/topics/impala_datetime_functions.xml
+++ b/docs/topics/impala_datetime_functions.xml
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?><!--
+<?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
@@ -20,7 +21,13 @@ under the License.
<concept id="datetime_functions">
<title>Impala Date and Time Functions</title>
- <titlealts audience="PDF"><navtitle>Date and Time Functions</navtitle></titlealts>
+
+ <titlealts audience="PDF">
+
+ <navtitle>Date and Time Functions</navtitle>
+
+ </titlealts>
+
<prolog>
<metadata>
<data name="Category" value="Impala"/>
@@ -37,32 +44,32 @@ under the License.
<p>
The underlying Impala data type for date and time data is
- <codeph><xref href="impala_timestamp.xml#timestamp">TIMESTAMP</xref></codeph>, which has both a date and a
- time portion. Functions that extract a single field, such as <codeph>hour()</codeph> or
- <codeph>minute()</codeph>, typically return an integer value. Functions that format the date portion, such as
- <codeph>date_add()</codeph> or <codeph>to_date()</codeph>, typically return a string value.
+ <codeph><xref href="impala_timestamp.xml#timestamp">TIMESTAMP</xref></codeph>, which has
+ both a date and a time portion. Functions that extract a single field, such as
+ <codeph>hour()</codeph> or <codeph>minute()</codeph>, typically return an integer value.
+ Functions that format the date portion, such as <codeph>date_add()</codeph> or
+ <codeph>to_date()</codeph>, typically return a string value.
</p>
<p>
- You can also adjust a <codeph>TIMESTAMP</codeph> value by adding or subtracting an <codeph>INTERVAL</codeph>
- expression. See <xref href="impala_timestamp.xml#timestamp"/> for details. <codeph>INTERVAL</codeph>
- expressions are also allowed as the second argument for the <codeph>date_add()</codeph> and
- <codeph>date_sub()</codeph> functions, rather than integers.
+ You can also adjust a <codeph>TIMESTAMP</codeph> value by adding or subtracting an
+ <codeph>INTERVAL</codeph> expression. See <xref href="impala_timestamp.xml#timestamp"/>
+ for details. <codeph>INTERVAL</codeph> expressions are also allowed as the second argument
+ for the <codeph>date_add()</codeph> and <codeph>date_sub()</codeph> functions, rather than
+ integers.
</p>
<p rev="2.2.0">
Some of these functions are affected by the setting of the
<codeph>--use_local_tz_for_unix_timestamp_conversions</codeph> startup flag for the
- <cmdname>impalad</cmdname> daemon. This setting is off by default, meaning that
- functions such as <codeph>from_unixtime()</codeph> and <codeph>unix_timestamp()</codeph>
- consider the input values to always represent the UTC time zone.
- This setting also applies when you <codeph>CAST()</codeph> a <codeph>BIGINT</codeph>
- value to <codeph>TIMESTAMP</codeph>, or a <codeph>TIMESTAMP</codeph>
- value to <codeph>BIGINT</codeph>.
- When this setting is enabled, these functions and operations convert to and from
- values representing the local time zone.
- See <xref href="impala_timestamp.xml#timestamp"/> for details about how
- Impala handles time zone considerations for the <codeph>TIMESTAMP</codeph> data type.
+ <cmdname>impalad</cmdname> daemon. This setting is off by default, meaning that functions
+ such as <codeph>from_unixtime()</codeph> and <codeph>unix_timestamp()</codeph> consider
+ the input values to always represent the UTC time zone. This setting also applies when you
+ <codeph>CAST()</codeph> a <codeph>BIGINT</codeph> value to <codeph>TIMESTAMP</codeph>, or
+ a <codeph>TIMESTAMP</codeph> value to <codeph>BIGINT</codeph>. When this setting is
+ enabled, these functions and operations convert to and from values representing the local
+ time zone. See <xref href="impala_timestamp.xml#timestamp"/> for details about how Impala
+ handles time zone considerations for the <codeph>TIMESTAMP</codeph> data type.
</p>
<p>
@@ -73,39 +80,278 @@ under the License.
Impala supports the following data and time functions:
</p>
-<!-- New for 2.3:
-int_months_between
-timeofday
-timestamp_cmp
-months_between
--->
+ <ul>
+ <li>
+ <xref href="#datetime_functions/add_months">ADD_MONTHS</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/adddate">ADDDATE</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/current_timestamp"
+ >CURRENT_TIMESTAMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/date_add">DATE_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/date_part">DATE_PART</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/date_sub">DATE_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/date_trunc">DATE_TRUNC</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/datediff">DATEDIFF</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/day">DAY</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/dayname">DAYNAME</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/dayofweek">DAYOFWEEK</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/dayofyear">DAYOFYEAR</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/days_add">DAYS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/days_sub">DAYS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/extract">EXTRACT</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/from_timestamp">FROM_TIMESTAMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/from_unixtime">FROM_UNIXTIME</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/from_utc_timestamp"
+ >FROM_UTC_TIMESTAMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/hour">HOUR</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/hours_add">HOURS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/hours_sub">HOURS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/int_months_between"
+ >INT_MONTHS_BETWEEN</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/microseconds_add"
+ >MICROSECONDS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/microseconds_sub"
+ >MICROSECONDS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/millisecond">MILLISECOND</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/milliseconds_add"
+ >MILLISECONDS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/milliseconds_sub"
+ >MILLISECONDS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/minute">MINUTE</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/minutes_add">MINUTES_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/minutes_sub">MINUTES_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/month">MONTH</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/month">MONTHNAME</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/monthname">MONTHS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/months_between">MONTHS_BETWEEN</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/months_sub">MONTHS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/nanoseconds_add">NANOSECONDS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/nanoseconds_sub">NANOSECONDS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/next_day">NEXT_DAY</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/now">NOW</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/quarter">QUARTER</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/second">SECOND</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/seconds_add">SECONDS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/seconds_sub">SECONDS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/subdate">SUBDATE</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/timeofday">TIMEOFDAY</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/timestamp_cmp">TIMESTAMP_CMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/to_date">TO_DATE</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/to_timestamp">TO_TIMESTAMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/to_utc_timestamp"
+ >TO_UTC_TIMESTAMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/trunc">TRUNC</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/unix_timestamp">UNIX_TIMESTAMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/utc_timestamp">UTC_TIMESTAMP</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/weekofyear">WEEKOFYEAR</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/weeks_add">WEEKS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/weeks_sub">WEEKS_SUB</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/year">YEAR</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/years_add">YEARS_ADD</xref>
+ </li>
+
+ <li>
+ <xref href="#datetime_functions/years_sub">YEARS_SUB</xref>
+ </li>
+ </ul>
<dl>
<dlentry rev="1.4.0" id="add_months">
<dt>
- <codeph>add_months(timestamp date, int months)</codeph>, <codeph>add_months(timestamp date, bigint
- months)</codeph>
+ ADD_MONTHS(TIMESTAMP date, INT months), ADD_MONTHS(TIMESTAMP date, BIGINT months)
</dt>
<dd>
- <indexterm audience="hidden">add_months() function</indexterm>
<b>Purpose:</b> Returns the specified date and time plus some number of months.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Same as <codeph><xref href="#datetime_functions/months_add">months_add()</xref></codeph>.
- Available in Impala 1.4 and higher. For
- compatibility when porting code with vendor extensions.
+ Same as
+ <codeph><xref href="#datetime_functions/months_add"
+ >MONTHS_ADD()</xref></codeph>.
+ Available in Impala 1.4 and higher. For compatibility when porting code with vendor
+ extensions.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples demonstrate adding months to construct the same
- day of the month in a different month; how if the current day of the month
- does not exist in the target month, the last day of that month is substituted;
- and how a negative argument produces a return value from a previous month.
+ The following examples demonstrate adding months to construct the same day of the
+ month in a different month; how if the current day of the month does not exist in
+ the target month, the last day of that month is substituted; and how a negative
+ argument produces a return value from a previous month.
</p>
<codeblock>
select now(), add_months(now(), 2);
@@ -136,22 +382,24 @@ select now(), add_months(now(), -1);
<dlentry rev="1.3.0" id="adddate">
<dt>
- <codeph>adddate(timestamp startdate, int days)</codeph>, <codeph>adddate(timestamp startdate, bigint
- days)</codeph>,
+ ADDDATE(TIMESTAMP startdate, INT days), ADDDATE(TIMESTAMP startdate, BIGINT days)
</dt>
<dd>
- <indexterm audience="hidden">adddate() function</indexterm>
- <b>Purpose:</b> Adds a specified number of days to a <codeph>TIMESTAMP</codeph> value. Similar to
- <codeph>date_add()</codeph>, but starts with an actual <codeph>TIMESTAMP</codeph> value instead of a
- string that is converted to a <codeph>TIMESTAMP</codeph>.
+ <b>Purpose:</b> Adds a specified number of days to a <codeph>TIMESTAMP</codeph> value.
+ Similar to <codeph>DATE_ADD()</codeph>, but starts with an actual
+ <codeph>TIMESTAMP</codeph> value instead of a string that is converted to a
+ <codeph>TIMESTAMP</codeph>.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show how to add a number of days to a <codeph>TIMESTAMP</codeph>.
- The number of days can also be negative, which gives the same effect as the <codeph>subdate()</codeph> function.
+ The following examples show how to add a number of days to a
+ <codeph>TIMESTAMP</codeph>. The number of days can also be negative, which gives the
+ same effect as the <codeph>subdate()</codeph> function.
</p>
<codeblock>
select now() as right_now, adddate(now(), 30) as now_plus_30;
@@ -175,15 +423,15 @@ select now() as right_now, adddate(now(), -15) as now_minus_15;
<dlentry id="current_timestamp">
<dt>
- <codeph>current_timestamp()</codeph>
+ CURRENT_TIMESTAMP()
</dt>
<dd>
- <indexterm audience="hidden">current_timestamp() function</indexterm>
- <b>Purpose:</b> Alias for the <codeph>now()</codeph> function.
+ <b>Purpose:</b> Alias for the <codeph>NOW()</codeph> function.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now(), current_timestamp();
@@ -208,25 +456,27 @@ select current_timestamp() as right_now,
<dlentry id="date_add">
<dt>
- <codeph>date_add(timestamp startdate, int days)</codeph>, <codeph>date_add(timestamp startdate,
- <varname>interval_expression</varname>)</codeph>
+ DATE_ADD(TIMESTAMP startdate, INT days), DATE_ADD(TIMESTAMP startdate,
+ interval_expression)
</dt>
<dd>
- <indexterm audience="hidden">date_add() function</indexterm>
<b>Purpose:</b> Adds a specified number of days to a <codeph>TIMESTAMP</codeph> value.
- <!-- Found this not to be true in latest release. I think the signature changed way back.
+<!-- Found this not to be true in latest release. I think the signature changed way back.
The first argument
can be a string, which is automatically cast to <codeph>TIMESTAMP</codeph> if it uses the recognized
format, as described in <xref href="impala_timestamp.xml#timestamp"/>.
-->
- With an <codeph>INTERVAL</codeph>
- expression as the second argument, you can calculate a delta value using other units such as weeks,
- years, hours, seconds, and so on; see <xref href="impala_timestamp.xml#timestamp"/> for details.
+ With an <codeph>INTERVAL</codeph> expression as the second argument, you can calculate
+ a delta value using other units such as weeks, years, hours, seconds, and so on; see
+ <xref
+ href="impala_timestamp.xml#timestamp"/> for details.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
The following example shows the simplest usage, of adding a specified number of days
to a <codeph>TIMESTAMP</codeph> value:
@@ -239,12 +489,11 @@ select now() as right_now, date_add(now(), 7) as next_week;
| 2016-05-20 11:03:48.687055000 | 2016-05-27 11:03:48.687055000 |
+-------------------------------+-------------------------------+
</codeblock>
-
<p>
The following examples show the shorthand notation of an <codeph>INTERVAL</codeph>
- expression, instead of specifying the precise number of days.
- The <codeph>INTERVAL</codeph> notation also lets you work with units smaller than
- a single day.
+ expression, instead of specifying the precise number of days. The
+ <codeph>INTERVAL</codeph> notation also lets you work with units smaller than a
+ single day.
</p>
<codeblock>
select now() as right_now, date_add(now(), interval 3 weeks) as in_3_weeks;
@@ -261,12 +510,11 @@ select now() as right_now, date_add(now(), interval 6 hours) as in_6_hours;
| 2016-05-20 11:13:51.492536000 | 2016-05-20 17:13:51.492536000 |
+-------------------------------+-------------------------------+
</codeblock>
-
<p>
Like all date/time functions that deal with months, <codeph>date_add()</codeph>
- handles nonexistent dates past the end of a month by setting the date to the
- last day of the month. The following example shows how the nonexistent date
- April 31st is normalized to April 30th:
+ handles nonexistent dates past the end of a month by setting the date to the last
+ day of the month. The following example shows how the nonexistent date April 31st is
+ normalized to April 30th:
</p>
<codeblock>
select date_add(cast('2016-01-31' as timestamp), interval 3 months) as 'april_31st';
@@ -283,18 +531,21 @@ select date_add(cast('2016-01-31' as timestamp), interval 3 months) as 'april_31
<dlentry rev="2.0.0" id="date_part">
<dt>
- <codeph>date_part(string, timestamp)</codeph>
+ DATE_PART(STRING part, TIMESTAMP date)
</dt>
<dd>
- <indexterm audience="hidden">date_part() function</indexterm>
<b>Purpose:</b> Similar to
- <xref href="impala_datetime_functions.xml#datetime_functions/extract"><codeph>EXTRACT()</codeph></xref>,
- with the argument order reversed. Supports the same date and time units as <codeph>EXTRACT()</codeph>.
- For compatibility with SQL code containing vendor extensions.
+ <xref
+ href="impala_datetime_functions.xml#datetime_functions/extract"
+ ><codeph>EXTRACT()</codeph></xref>,
+ with the argument order reversed. Supports the same date and time units as
+ <codeph>EXTRACT()</codeph>. For compatibility with SQL code containing vendor
+ extensions.
<p>
- <b>Return type:</b> <codeph>bigint</codeph>
+ <b>Return type:</b> <codeph>BIGINT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select date_part('year',now()) as current_year;
@@ -318,28 +569,30 @@ select date_part('hour',now()) as hour_of_day;
<dlentry id="date_sub">
<dt>
- <codeph>date_sub(timestamp startdate, int days)</codeph>, <codeph>date_sub(timestamp startdate,
- <varname>interval_expression</varname>)</codeph>
+ DATE_SUB(TIMESTAMP startdate, INT days), DATE_SUB(TIMESTAMP startdate,
+ interval_expression)
</dt>
<dd>
- <indexterm audience="hidden">date_sub() function</indexterm>
- <b>Purpose:</b> Subtracts a specified number of days from a <codeph>TIMESTAMP</codeph> value.
- <!-- Found this not to be true in latest release. I think the signature changed way back.
+ <b>Purpose:</b> Subtracts a specified number of days from a <codeph>TIMESTAMP</codeph>
+ value.
+<!-- Found this not to be true in latest release. I think the signature changed way back.
The first argument can be a string, which is automatically cast to <codeph>TIMESTAMP</codeph> if it uses the
recognized format, as described in <xref href="impala_timestamp.xml#timestamp"/>.
-->
- With an
- <codeph>INTERVAL</codeph> expression as the second argument, you can calculate a delta value using other
- units such as weeks, years, hours, seconds, and so on; see <xref href="impala_timestamp.xml#timestamp"/>
- for details.
+ With an <codeph>INTERVAL</codeph> expression as the second argument, you can calculate
+ a delta value using other units such as weeks, years, hours, seconds, and so on; see
+ <xref
+ href="impala_timestamp.xml#timestamp"/> for details.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following example shows the simplest usage, of subtracting a specified number of days
- from a <codeph>TIMESTAMP</codeph> value:
+ The following example shows the simplest usage, of subtracting a specified number of
+ days from a <codeph>TIMESTAMP</codeph> value:
</p>
<codeblock>
select now() as right_now, date_sub(now(), 7) as last_week;
@@ -351,9 +604,9 @@ select now() as right_now, date_sub(now(), 7) as last_week;
</codeblock>
<p>
The following examples show the shorthand notation of an <codeph>INTERVAL</codeph>
- expression, instead of specifying the precise number of days.
- The <codeph>INTERVAL</codeph> notation also lets you work with units smaller than
- a single day.
+ expression, instead of specifying the precise number of days. The
+ <codeph>INTERVAL</codeph> notation also lets you work with units smaller than a
+ single day.
</p>
<codeblock>
select now() as right_now, date_sub(now(), interval 3 weeks) as 3_weeks_ago;
@@ -370,12 +623,11 @@ select now() as right_now, date_sub(now(), interval 6 hours) as 6_hours_ago;
| 2016-05-20 11:23:35.439631000 | 2016-05-20 05:23:35.439631000 |
+-------------------------------+-------------------------------+
</codeblock>
-
<p>
Like all date/time functions that deal with months, <codeph>date_add()</codeph>
- handles nonexistent dates past the end of a month by setting the date to the
- last day of the month. The following example shows how the nonexistent date
- April 31st is normalized to April 30th:
+ handles nonexistent dates past the end of a month by setting the date to the last
+ day of the month. The following example shows how the nonexistent date April 31st is
+ normalized to April 30th:
</p>
<codeblock>
select date_sub(cast('2016-05-31' as timestamp), interval 1 months) as 'april_31st';
@@ -392,72 +644,117 @@ select date_sub(cast('2016-05-31' as timestamp), interval 1 months) as 'april_31
<dlentry rev="2.11.0 IMPALA-5317" id="date_trunc">
<dt>
- <codeph>date_trunc(string unit, timestamp)</codeph>
+ DATE_TRUNC(STRING unit, TIMESTAMP ts)
</dt>
<dd>
- <indexterm audience="hidden">date_trunc() function</indexterm>
- <b>Purpose:</b> Truncates a <codeph>TIMESTAMP</codeph> value to the specified precision.
+ <b>Purpose:</b> Truncates a <codeph>TIMESTAMP</codeph> value to the specified
+ precision.
<p>
<b>Unit argument:</b> The <codeph>unit</codeph> argument value for truncating
- <codeph>TIMESTAMP</codeph> values is not case-sensitive. This argument string
- can be one of:
+ <codeph>TIMESTAMP</codeph> values is not case-sensitive. This argument string can be
+ one of:
</p>
<ul>
- <li>microseconds</li>
- <li>milliseconds</li>
- <li>second</li>
- <li>minute</li>
- <li>hour</li>
- <li>day</li>
- <li>week</li>
- <li>month</li>
- <li>year</li>
- <li>decade</li>
- <li>century</li>
- <li>millennium</li>
+ <li>
+ microseconds
+ </li>
+
+ <li>
+ milliseconds
+ </li>
+
+ <li>
+ second
+ </li>
+
+ <li>
+ minute
+ </li>
+
+ <li>
+ hour
+ </li>
+
+ <li>
+ day
+ </li>
+
+ <li>
+ week
+ </li>
+
+ <li>
+ month
+ </li>
+
+ <li>
+ year
+ </li>
+
+ <li>
+ decade
+ </li>
+
+ <li>
+ century
+ </li>
+
+ <li>
+ millennium
+ </li>
</ul>
<p>
- For example, calling <codeph>date_trunc('hour',ts)</codeph> truncates
- <codeph>ts</codeph> to the beginning of the corresponding hour, with
- all minutes, seconds, milliseconds, and so on set to zero. Calling
- <codeph>date_trunc('milliseconds',ts)</codeph> truncates
- <codeph>ts</codeph> to the beginning of the corresponding millisecond,
- with all microseconds and nanoseconds set to zero.
+ For example, calling <codeph>DATE_TRUNC('hour',ts)</codeph> truncates
+ <codeph>ts</codeph> to the beginning of the corresponding hour, with all minutes,
+ seconds, milliseconds, and so on set to zero. Calling
+ <codeph>DATE_TRUNC('milliseconds',ts)</codeph> truncates <codeph>ts</codeph> to the
+ beginning of the corresponding millisecond, with all microseconds and nanoseconds
+ set to zero.
</p>
+
<note>
- The sub-second units are specified in plural form. All units representing
- one second or more are specified in singular form.
+ The sub-second units are specified in plural form. All units representing one second
+ or more are specified in singular form.
</note>
+
<p conref="../shared/impala_common.xml#common/added_in_2110"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Although this function is similar to calling <codeph>TRUNC()</codeph>
- with a <codeph>TIMESTAMP</codeph> argument, the order of arguments
- and the recognized units are different between <codeph>TRUNC()</codeph>
- and <codeph>DATE_TRUNC()</codeph>. Therefore, these functions are not
- interchangeable.
+ Although this function is similar to calling <codeph>TRUNC()</codeph> with a
+ <codeph>TIMESTAMP</codeph> argument, the order of arguments and the recognized units
+ are different between <codeph>TRUNC()</codeph> and <codeph>DATE_TRUNC()</codeph>.
+ Therefore, these functions are not interchangeable.
</p>
+
<p>
- This function is typically used in <codeph>GROUP BY</codeph>
- queries to aggregate results from the same hour, day, week, month, quarter, and so on.
- You can also use this function in an <codeph>INSERT ... SELECT</codeph> into a
- partitioned table to divide <codeph>TIMESTAMP</codeph> values into the correct partition.
+ This function is typically used in <codeph>GROUP BY</codeph> queries to aggregate
+ results from the same hour, day, week, month, quarter, and so on. You can also use
+ this function in an <codeph>INSERT ... SELECT</codeph> into a partitioned table to
+ divide <codeph>TIMESTAMP</codeph> values into the correct partition.
</p>
+
<p>
Because the return value is a <codeph>TIMESTAMP</codeph>, if you cast the result of
- <codeph>DATE_TRUNC()</codeph> to <codeph>STRING</codeph>, you will often see zeroed-out portions such as
- <codeph>00:00:00</codeph> in the time field. If you only need the individual units such as hour, day,
- month, or year, use the <codeph>EXTRACT()</codeph> function instead. If you need the individual units
- from a truncated <codeph>TIMESTAMP</codeph> value, run the <codeph>TRUNCATE()</codeph> function on the
- original value, then run <codeph>EXTRACT()</codeph> on the result.
+ <codeph>DATE_TRUNC()</codeph> to <codeph>STRING</codeph>, you will often see
+ zeroed-out portions such as <codeph>00:00:00</codeph> in the time field. If you only
+ need the individual units such as hour, day, month, or year, use the
+ <codeph>EXTRACT()</codeph> function instead. If you need the individual units from a
+ truncated <codeph>TIMESTAMP</codeph> value, run the <codeph>TRUNCATE()</codeph>
+ function on the original value, then run <codeph>EXTRACT()</codeph> on the result.
</p>
+
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show how to call <codeph>DATE_TRUNC()</codeph> with different unit values:
+ The following examples show how to call <codeph>DATE_TRUNC()</codeph> with different
+ unit values:
</p>
<codeblock>
select now(), date_trunc('second', now());
@@ -488,30 +785,33 @@ select now(), date_trunc('millennium', now());
<dlentry id="datediff">
<dt>
- <codeph>datediff(timestamp enddate, timestamp startdate)</codeph>
+ DATEDIFF(TIMESTAMP enddate, TIMESTAMP startdate)
</dt>
<dd>
- <indexterm audience="hidden">datediff() function</indexterm>
- <b>Purpose:</b> Returns the number of days between two <codeph>TIMESTAMP</codeph> values.
+ <b>Purpose:</b> Returns the number of days between two <codeph>TIMESTAMP</codeph>
+ values.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- If the first argument represents a later date than the second argument,
- the return value is positive. If both arguments represent the same date,
- the return value is zero. The time portions of the <codeph>TIMESTAMP</codeph>
- values are irrelevant. For example, 11:59 PM on one day and 12:01 on the next
- day represent a <codeph>datediff()</codeph> of -1 because the date/time values
- represent different days, even though the <codeph>TIMESTAMP</codeph> values differ by only 2 minutes.
+ If the first argument represents a later date than the second argument, the return
+ value is positive. If both arguments represent the same date, the return value is
+ zero. The time portions of the <codeph>TIMESTAMP</codeph> values are irrelevant. For
+ example, 11:59 PM on one day and 12:01 on the next day represent a
+ <codeph>datediff()</codeph> of -1 because the date/time values represent different
+ days, even though the <codeph>TIMESTAMP</codeph> values differ by only 2 minutes.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following example shows how comparing a <q>late</q> value with
- an <q>earlier</q> value produces a positive number. In this case,
- the result is (365 * 5) + 1, because one of the intervening years is
- a leap year.
+ The following example shows how comparing a <q>late</q> value with an <q>earlier</q>
+ value produces a positive number. In this case, the result is (365 * 5) + 1, because
+ one of the intervening years is a leap year.
</p>
<codeblock>
select now() as right_now, datediff(now() + interval 5 years, now()) as in_5_years;
@@ -523,11 +823,11 @@ select now() as right_now, datediff(now() + interval 5 years, now()) as in_5_yea
</codeblock>
<p>
The following examples show how the return value represent the number of days
- between the associated dates, regardless of the time portion of each <codeph>TIMESTAMP</codeph>.
- For example, different times on the same day produce a <codeph>date_diff()</codeph> of 0,
- regardless of which one is earlier or later. But if the arguments represent different dates,
- <codeph>date_diff()</codeph> returns a non-zero integer value, regardless of the time portions
- of the dates.
+ between the associated dates, regardless of the time portion of each
+ <codeph>TIMESTAMP</codeph>. For example, different times on the same day produce a
+ <codeph>date_diff()</codeph> of 0, regardless of which one is earlier or later. But
+ if the arguments represent different dates, <codeph>date_diff()</codeph> returns a
+ non-zero integer value, regardless of the time portions of the dates.
</p>
<codeblock>
select now() as right_now, datediff(now(), now() + interval 4 hours) as in_4_hours;
@@ -565,22 +865,22 @@ select now() as right_now, datediff(now(), now() - interval 18 hours) as 18_hour
<dlentry id="day">
<dt>
- <codeph>day(timestamp date), <ph id="dayofmonth"
- >dayofmonth(timestamp date)</ph></codeph>
+ DAY(TIMESTAMP date), DAYOFMONTH(TIMESTAMP date)
</dt>
<dd>
- <indexterm audience="hidden">day() function</indexterm>
- <b>Purpose:</b> Returns the day field from the date portion of a <codeph>TIMESTAMP</codeph>.
- The value represents the day of the month, therefore is in the range 1-31, or less for
- months without 31 days.
+ <b>Purpose:</b> Returns the day field from the date portion of a
+ <codeph>TIMESTAMP</codeph>. The value represents the day of the month, therefore is in
+ the range 1-31, or less for months without 31 days.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show how the day value corresponds to the day
- of the month, resetting back to 1 at the start of each month.
+ The following examples show how the day value corresponds to the day of the month,
+ resetting back to 1 at the start of each month.
</p>
<codeblock>
select now(), day(now());
@@ -605,8 +905,8 @@ select now() + interval 12 days, day(now() + interval 12 days);
+-------------------------------+-------------------------------+
</codeblock>
<p>
- The following examples show how the day value is <codeph>NULL</codeph>
- for nonexistent dates or misformatted date strings.
+ The following examples show how the day value is <codeph>NULL</codeph> for
+ nonexistent dates or misformatted date strings.
</p>
<codeblock>
-- 2016 is a leap year, so it has a Feb. 29.
@@ -641,23 +941,24 @@ select day('2016-02-028');
<dlentry rev="1.2" id="dayname">
<dt>
- <codeph>dayname(timestamp date)</codeph>
+ DAYNAME(TIMESTAMP date)
</dt>
<dd>
- <indexterm audience="hidden">dayname() function</indexterm>
- <b>Purpose:</b> Returns the day field from a <codeph>TIMESTAMP</codeph> value, converted to the string
- corresponding to that day name. The range of return values is <codeph>'Sunday'</codeph> to
- <codeph>'Saturday'</codeph>. Used in report-generating queries, as an alternative to calling
- <codeph>dayofweek()</codeph> and turning that numeric return value into a string using a
- <codeph>CASE</codeph> expression.
+ <b>Purpose:</b> Returns the day field from a <codeph>TIMESTAMP</codeph> value,
+ converted to the string corresponding to that day name. The range of return values is
+ <codeph>'Sunday'</codeph> to <codeph>'Saturday'</codeph>. Used in report-generating
+ queries, as an alternative to calling <codeph>DAYOFWEEK()</codeph> and turning that
+ numeric return value into a string using a <codeph>CASE</codeph> expression.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show the day name associated with
- <codeph>TIMESTAMP</codeph> values representing different days.
+ The following examples show the day name associated with <codeph>TIMESTAMP</codeph>
+ values representing different days.
</p>
<codeblock>
select now() as right_now,
@@ -684,16 +985,17 @@ select now() + interval 1 day as tomorrow,
<dlentry rev="1.1" id="dayofweek">
<dt>
- <codeph>dayofweek(timestamp date)</codeph>
+ DAYOFWEEK(TIMESTAMP date)
</dt>
<dd>
- <indexterm audience="hidden">dayofweek() function</indexterm>
- <b>Purpose:</b> Returns the day field from the date portion of a <codeph>TIMESTAMP</codeph>, corresponding to the day of
- the week. The range of return values is 1 (Sunday) to 7 (Saturday).
+ <b>Purpose:</b> Returns the day field from the date portion of a
+ <codeph>TIMESTAMP</codeph>, corresponding to the day of the week. The range of return
+ values is 1 (Sunday) to 7 (Saturday).
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now,
@@ -712,23 +1014,23 @@ select now() as right_now,
<dlentry rev="1.3.0" id="dayofyear">
<dt>
- <codeph>dayofyear(timestamp date)</codeph>
+ DAYOFYEAR(TIMESTAMP date)
</dt>
<dd>
- <indexterm audience="hidden">dayofyear() function</indexterm>
- <b>Purpose:</b> Returns the day field from a <codeph>TIMESTAMP</codeph> value, corresponding to the day
- of the year. The range of return values is 1 (January 1) to 366 (December 31 of a leap year).
+ <b>Purpose:</b> Returns the day field from a <codeph>TIMESTAMP</codeph> value,
+ corresponding to the day of the year. The range of return values is 1 (January 1) to
+ 366 (December 31 of a leap year).
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show return values from the
- <codeph>dayofyear()</codeph> function. The same date
- in different years returns a different day number
- for all dates after February 28,
- because 2016 is a leap year while 2015 is not a leap year.
+ The following examples show return values from the <codeph>DAYOFYEAR()</codeph>
+ function. The same date in different years returns a different day number for all
+ dates after February 28, because 2016 is a leap year while 2015 is not a leap year.
</p>
<codeblock>
select now() as right_now,
@@ -754,18 +1056,18 @@ select now() - interval 1 year as last_year,
<dlentry rev="1.3.0" id="days_add">
<dt>
- <codeph>days_add(timestamp startdate, int days)</codeph>, <codeph>days_add(timestamp startdate, bigint
- days)</codeph>
+ DAYS_ADD(TIMESTAMP startdate, INT days), DAYS_ADD(TIMESTAMP startdate, BIGINT days)
</dt>
<dd>
- <indexterm audience="hidden">days_add() function</indexterm>
- <b>Purpose:</b> Adds a specified number of days to a <codeph>TIMESTAMP</codeph> value. Similar to
- <codeph>date_add()</codeph>, but starts with an actual <codeph>TIMESTAMP</codeph> value instead of a
- string that is converted to a <codeph>TIMESTAMP</codeph>.
+ <b>Purpose:</b> Adds a specified number of days to a <codeph>TIMESTAMP</codeph> value.
+ Similar to <codeph>date_add()</codeph>, but starts with an actual
+ <codeph>TIMESTAMP</codeph> value instead of a string that is converted to a
+ <codeph>TIMESTAMP</codeph>.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now, days_add(now(), 31) as 31_days_later;
@@ -782,18 +1084,18 @@ select now() as right_now, days_add(now(), 31) as 31_days_later;
<dlentry rev="1.3.0" id="days_sub">
<dt>
- <codeph>days_sub(timestamp startdate, int days)</codeph>, <codeph>days_sub(timestamp startdate, bigint
- days)</codeph>
+ DAYS_SUB(TIMESTAMP startdate, INT days), DAYS_SUB(TIMESTAMP startdate, BIGINT days)
</dt>
<dd>
- <indexterm audience="hidden">days_sub() function</indexterm>
- <b>Purpose:</b> Subtracts a specified number of days from a <codeph>TIMESTAMP</codeph> value. Similar to
- <codeph>date_sub()</codeph>, but starts with an actual <codeph>TIMESTAMP</codeph> value instead of a
- string that is converted to a <codeph>TIMESTAMP</codeph>.
+ <b>Purpose:</b> Subtracts a specified number of days from a <codeph>TIMESTAMP</codeph>
+ value. Similar to <codeph>DATE_SUB()</codeph>, but starts with an actual
+ <codeph>TIMESTAMP</codeph> value instead of a string that is converted to a
+ <codeph>TIMESTAMP</codeph>.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now, days_sub(now(), 31) as 31_days_ago;
@@ -810,61 +1112,59 @@ select now() as right_now, days_sub(now(), 31) as 31_days_ago;
<dlentry rev="1.4.0" id="extract">
<dt>
- <codeph>extract(timestamp, string unit)</codeph>, <codeph rev="2.0.0">extract(unit FROM timestamp)</codeph>
+ EXTRACT(TIMESTAMP ts, STRING unit), EXTRACT(unit FROM TIMESTAMP ts)
</dt>
<dd>
- <indexterm audience="hidden">extract() function</indexterm>
<b>Purpose:</b> Returns one of the numeric date or time fields from a
- <codeph>TIMESTAMP</codeph> value. <p>
+ <codeph>TIMESTAMP</codeph> value.
+ <p>
<b>Unit argument:</b> The <codeph>unit</codeph> string can be one of
- <codeph>epoch</codeph>, <codeph>year</codeph>,
- <codeph>quarter</codeph>, <codeph>month</codeph>,
- <codeph>day</codeph>, <codeph>hour</codeph>,
- <codeph>minute</codeph>, <codeph>second</codeph>, or
- <codeph>millisecond</codeph>. This argument value is
- case-insensitive. </p><p>If you specify <codeph>millisecond</codeph>
- for the <codeph>unit</codeph> argument, the function returns the
- seconds component and the milliseconds component. For example,
- <codeph>extract(cast('2006-05-12 18:27:28.123456789' as
- timestamp), 'MILLISECOND')</codeph> will return
- <codeph>28123</codeph>. </p><p rev="2.0.0"> In Impala 2.0 and
- higher, you can use special syntax rather than a regular function
- call, for compatibility with code that uses the SQL-99 format with
- the <codeph>FROM</codeph> keyword. With this style, the unit names
- are identifiers rather than <codeph>STRING</codeph> literals. For
- example, the following calls are both equivalent:
- <codeblock>extract(year from now());
-extract(now(), "year");
+ <codeph>epoch</codeph>, <codeph>year</codeph>, <codeph>quarter</codeph>,
+ <codeph>month</codeph>, <codeph>day</codeph>, <codeph>hour</codeph>,
+ <codeph>minute</codeph>, <codeph>second</codeph>, or <codeph>millisecond</codeph>.
+ This argument value is case-insensitive.
+ </p>
+
+ <p>
+ If you specify <codeph>millisecond</codeph> for the <codeph>unit</codeph> argument,
+ the function returns the seconds component and the milliseconds component. For
+ example, <codeph>EXTRACT(CAST('2006-05-12 18:27:28.123456789' AS TIMESTAMP),
+ 'MILLISECOND')</codeph> will return <codeph>28123</codeph>.
+ </p>
+
+ <p rev="2.0.0">
+ In Impala 2.0 and higher, you can use special syntax rather than a regular function
+ call, for compatibility with code that uses the SQL-99 format with the
+ <codeph>FROM</codeph> keyword. With this style, the unit names are identifiers
+ rather than <codeph>STRING</codeph> literals. For example, the following calls are
+ equivalent:
+<codeblock>EXTRACT(year FROM NOW());
+EXTRACT(NOW(), 'year');
</codeblock>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p> Typically used in <codeph>GROUP BY</codeph> queries to arrange
- results by hour, day, month, and so on. You can also use this
- function in an <codeph>INSERT ... SELECT</codeph> into a partitioned
- table to split up <codeph>TIMESTAMP</codeph> values into individual
- parts, if the partitioned table has separate partition key columns
- representing year, month, day, and so on. If you need to divide by
- more complex units of time, such as by week or by quarter, use the
- <codeph>TRUNC()</codeph> function instead. </p>
- <p>
- <b>Return type:</b>
- <codeph>bigint</codeph>
+
+ <p>
+ Typically used in <codeph>GROUP BY</codeph> queries to arrange results by hour, day,
+ month, and so on. You can also use this function in an <codeph>INSERT ...
+ SELECT</codeph> statement to insert into a partitioned table to split up
+ <codeph>TIMESTAMP</codeph> values into individual parts, if the partitioned table
+ has separate partition key columns representing year, month, day, and so on. If you
+ need to divide by more complex units of time, such as by week or by quarter, use the
+ <codeph>TRUNC()</codeph> function instead.
</p>
- <p conref="../shared/impala_common.xml#common/example_blurb"/>
- <codeblock>
-select now() as right_now,
- extract(year from now()) as this_year,
- extract(month from now()) as this_month;
-+-------------------------------+-----------+------------+
-| right_now | this_year | this_month |
-+-------------------------------+-----------+------------+
-| 2016-05-31 11:18:43.310328000 | 2016 | 5 |
-+-------------------------------+-----------+------------+
-select now() as right_now,
- extract(day from now()) as this_day,
- extract(hour from now()) as this_hour;
+ <p>
+ <b>Return type:</b> <codeph>BIGINT</codeph>
+ </p>
+
+ <p conref="../shared/impala_common.xml#common/example_blurb"/>
+<codeblock>
+SELECT NOW() AS right_now,
+ EXTRACT(day FROM NOW()) AS this_day,
+ EXTRACT(hour FROM NOW()) AS this_hour;
+-------------------------------+----------+-----------+
| right_now | this_day | this_hour |
+-------------------------------+----------+-----------+
@@ -878,55 +1178,57 @@ select now() as right_now,
<dlentry id="from_timestamp" rev="2.3.0 IMPALA-2190">
<dt>
- <codeph>from_timestamp(datetime timestamp, pattern string)</codeph>
+ FROM_TIMESTAMP(TIMESTAMP datetime, STRING pattern), FROM_TIMESTAMP(STRING datetime,
+ STRING pattern)
</dt>
<dd>
- <indexterm audience="hidden">from_timestamp() function</indexterm>
- <b>Purpose:</b> Converts a <codeph>TIMESTAMP</codeph> value into a
- string representing the same value.
+ <b>Purpose:</b> Converts a <codeph>TIMESTAMP</codeph> value into a string representing
+ the same value.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- The <codeph>from_timestamp()</codeph> function provides a flexible way to convert <codeph>TIMESTAMP</codeph>
- values into arbitrary string formats for reporting purposes.
+ The <codeph>FROM_TIMESTAMP()</codeph> function provides a flexible way to convert
+ <codeph>TIMESTAMP</codeph> values into arbitrary string formats for reporting
+ purposes.
</p>
+
<p>
- Because Impala implicitly converts string values into <codeph>TIMESTAMP</codeph>, you can
- pass date/time values represented as strings (in the standard <codeph>yyyy-MM-dd HH:mm:ss.SSS</codeph> format)
- to this function. The result is a string using different separator characters, order of fields, spelled-out month
+ Because Impala implicitly converts string values into <codeph>TIMESTAMP</codeph>,
+ you can pass date/time values represented as strings (in the standard
+ <codeph>yyyy-MM-dd HH:mm:ss.SSS</codeph> format) to this function. The result is a
+ string using different separator characters, order of fields, spelled-out month
names, or other variation of the date/time string representation.
</p>
+
<p>
- The allowed tokens for the pattern string are the same as for the <codeph>from_unixtime()</codeph> function.
+ The allowed tokens for the pattern string are the same as for the
+ <codeph>FROM_UNIXTIME()</codeph> function.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
The following examples show different ways to format a <codeph>TIMESTAMP</codeph>
value as a string:
</p>
<codeblock>
--- Reformat arbitrary TIMESTAMP value.
-select from_timestamp(now(), 'yyyy/MM/dd');
+-- Reformat a TIMESTAMP value.
+SELECT FROM_TIMESTAMP(NOW(), 'yyyy/MM/dd');
+-------------------------------------+
| from_timestamp(now(), 'yyyy/mm/dd') |
+-------------------------------------+
-| 2017/10/01 |
+| 2018/10/09 |
+-------------------------------------+
--- Reformat string literal representing date/time.
-select from_timestamp('1984-09-25', 'yyyy/MM/dd');
-+--------------------------------------------+
-| from_timestamp('1984-09-25', 'yyyy/mm/dd') |
-+--------------------------------------------+
-| 1984/09/25 |
-+--------------------------------------------+
-
-- Alternative format for reporting purposes.
-select from_timestamp('1984-09-25 16:45:30.125', 'MMM dd, yyyy HH:mm:ss.SSS');
+SELECT FROM_TIMESTAMP('1984-09-25 16:45:30.125', 'MMM dd, yyyy HH:mm:ss.SSS');
+------------------------------------------------------------------------+
| from_timestamp('1984-09-25 16:45:30.125', 'mmm dd, yyyy hh:mm:ss.sss') |
+------------------------------------------------------------------------+
@@ -940,75 +1242,75 @@ select from_timestamp('1984-09-25 16:45:30.125', 'MMM dd, yyyy HH:mm:ss.SSS');
<dlentry id="from_unixtime">
<dt>
- <codeph>from_unixtime(bigint unixtime[, string format])</codeph>
+ FROM_UNIXTIME(BIGINT unixtime[, STRING format])
</dt>
<dd>
- <indexterm audience="hidden">from_unixtime() function</indexterm>
- <b>Purpose:</b> Converts the number of seconds from the Unix epoch to the specified time into a string in
- the local time zone.
+ <b>Purpose:</b> Converts the number of seconds from the Unix epoch to the specified
+ time into a string in the local time zone.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/y2k38"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
The format string accepts the variations allowed for the <codeph>TIMESTAMP</codeph>
- data type: date plus time, date by itself, time by itself, and optional fractional seconds for the
- time. See <xref href="impala_timestamp.xml#timestamp"/> for details.
+ data type: date plus time, date by itself, time by itself, and optional fractional
+ seconds for the time. See <xref href="impala_timestamp.xml#timestamp"/> for details.
</p>
+
<p rev="1.3.0">
- Currently, the format string is case-sensitive, especially to distinguish <codeph>m</codeph> for
- minutes and <codeph>M</codeph> for months. In Impala 1.3 and later, you can switch the order of
- elements, use alternative separator characters, and use a different number of placeholders for each
- unit. Adding more instances of <codeph>y</codeph>, <codeph>d</codeph>, <codeph>H</codeph>, and so on
- produces output strings zero-padded to the requested number of characters. The exception is
- <codeph>M</codeph> for months, where <codeph>M</codeph> produces a non-padded value such as
- <codeph>3</codeph>, <codeph>MM</codeph> produces a zero-padded value such as <codeph>03</codeph>,
- <codeph>MMM</codeph> produces an abbreviated month name such as <codeph>Mar</codeph>, and sequences of
- 4 or more <codeph>M</codeph> are not allowed. A date string including all fields could be
- <codeph>"yyyy-MM-dd HH:mm:ss.SSSSSS"</codeph>, <codeph>"dd/MM/yyyy HH:mm:ss.SSSSSS"</codeph>,
- <codeph>"MMM dd, yyyy HH.mm.ss (SSSSSS)"</codeph> or other combinations of placeholders and separator
- characters.
- </p>
- <p conref="../shared/impala_common.xml#common/timezone_conversion_caveat"/>
+ Currently, the format string is case-sensitive, especially to distinguish
+ <codeph>m</codeph> for minutes and <codeph>M</codeph> for months. In Impala 1.3 and
+ later, you can switch the order of elements, use alternative separator characters,
+ and use a different number of placeholders for each unit. Adding more instances of
+ <codeph>y</codeph>, <codeph>d</codeph>, <codeph>H</codeph>, and so on produces
+ output strings zero-padded to the requested number of characters. The exception is
+ <codeph>M</codeph> for months, where <codeph>M</codeph> produces a non-padded value
+ such as <codeph>3</codeph>, <codeph>MM</codeph> produces a zero-padded value such as
+ <codeph>03</codeph>, <codeph>MMM</codeph> produces an abbreviated month name such as
+ <codeph>Mar</codeph>, and sequences of 4 or more <codeph>M</codeph> are not allowed.
+ A date string including all fields could be <codeph>'yyyy-MM-dd
+ HH:mm:ss.SSSSSS'</codeph>, <codeph>'dd/MM/yyyy HH:mm:ss.SSSSSS'</codeph>,
+ <codeph>'MMM dd, yyyy HH.mm.ss (SSSSSS)'</codeph> or other combinations of
+ placeholders and separator characters.
+ </p>
+
+ <p
+ conref="../shared/impala_common.xml#common/timezone_conversion_caveat"/>
+
<note rev="1.3.0">
<p rev="1.3.0">
- The more flexible format strings allowed with the built-in functions do not change the rules about
- using <codeph>CAST()</codeph> to convert from a string to a <codeph>TIMESTAMP</codeph> value. Strings
- being converted through <codeph>CAST()</codeph> must still have the elements in the specified order and use the specified delimiter
- characters, as described in <xref href="impala_timestamp.xml#timestamp"/>.
+ The more flexible format strings allowed with the built-in functions do not change
+ the rules about using <codeph>CAST()</codeph> to convert from a string to a
+ <codeph>TIMESTAMP</codeph> value. Strings being converted through
+ <codeph>CAST()</codeph> must still have the elements in the specified order and
+ use the specified delimiter characters, as described in
+ <xref href="impala_timestamp.xml#timestamp"/>.
</p>
</note>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<codeblock>select from_unixtime(1392394861,"yyyy-MM-dd HH:mm:ss.SSSS");
+<codeblock>SELECT FROM_UNIXTIME(1392394861,'yyyy-MM-dd HH:mm:ss.SSSS');
+-------------------------------------------------------+
| from_unixtime(1392394861, 'yyyy-mm-dd hh:mm:ss.ssss') |
+-------------------------------------------------------+
| 2014-02-14 16:21:01.0000 |
+-------------------------------------------------------+
-select from_unixtime(1392394861,"yyyy-MM-dd");
-+-----------------------------------------+
-| from_unixtime(1392394861, 'yyyy-mm-dd') |
-+-----------------------------------------+
-| 2014-02-14 |
-+-----------------------------------------+
-
-select from_unixtime(1392394861,"HH:mm:ss.SSSS");
+SELECT FROM_UNIXTIME(1392394861,'HH:mm:ss.SSSS');
+--------------------------------------------+
| from_unixtime(1392394861, 'hh:mm:ss.ssss') |
+--------------------------------------------+
| 16:21:01.0000 |
+--------------------------------------------+
-
-select from_unixtime(1392394861,"HH:mm:ss");
-+---------------------------------------+
-| from_unixtime(1392394861, 'hh:mm:ss') |
-+---------------------------------------+
-| 16:21:01 |
-+---------------------------------------+</codeblock>
- <p conref="../shared/impala_common.xml#common/datetime_function_chaining"/>
+</codeblock>
+ <p
+ conref="../shared/impala_common.xml#common/datetime_function_chaining"
+ />
</dd>
</dlentry>
@@ -1016,29 +1318,37 @@ select from_unixtime(1392394861,"HH:mm:ss");
<dlentry id="from_utc_timestamp">
<dt>
- <codeph>from_utc_timestamp(timestamp, string timezone)</codeph>
+ FROM_UTC_TIMESTAMP(TIMESTAMP ts, STRING timezone)
</dt>
<dd>
- <indexterm audience="hidden">from_utc_timestamp() function</indexterm>
- <b>Purpose:</b> Converts a specified UTC timestamp value into the appropriate value for a specified time
- zone.
+ <b>Purpose:</b> Converts a specified UTC timestamp value into the appropriate value
+ for a specified time zone.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p>
- <b>Usage notes:</b> Often used to translate UTC time zone data stored in a table back to the local
- date and time for reporting. The opposite of the <codeph>to_utc_timestamp()</codeph> function.
+ <b>Usage notes:</b> Often used to translate UTC time zone data stored in a table
+ back to the local date and time for reporting. The opposite of the
+ <codeph>TO_UTC_TIMESTAMP()</codeph> function.
</p>
+
<p conref="../shared/impala_common.xml#common/current_timezone_tip"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- See discussion of time zones in <xref href="impala_timestamp.xml#timestamp"/>
- for information about using this function for conversions between the local time zone and UTC.
+ See discussion of time zones in
+ <xref
+ href="impala_timestamp.xml#timestamp"/> for information about
+ using this function for conversions between the local time zone and UTC.
</p>
+
<p>
- The following example shows how when <codeph>TIMESTAMP</codeph> values representing the UTC time zone
- are stored in a table, a query can display the equivalent local date and time for a different time zone.
+ The following example shows how when <codeph>TIMESTAMP</codeph> values representing
+ the UTC time zone are stored in a table, a query can display the equivalent local
+ date and time for a different time zone.
</p>
<codeblock>
with t1 as (select cast('2016-06-02 16:25:36.116143000' as timestamp) as utc_datetime)
@@ -1053,11 +1363,10 @@ with t1 as (select cast('2016-06-02 16:25:36.116143000' as timestamp) as utc_dat
+-------------------------------+-------------------------------+
</codeblock>
<p>
- The following example shows that for a date and time when daylight savings
- is in effect (<codeph>PDT</codeph>), the UTC time
- is 7 hours ahead of the local California time; while when daylight savings
- is not in effect (<codeph>PST</codeph>), the UTC time is 8 hours ahead of
- the local California time.
+ The following example shows that for a date and time when daylight savings is in
+ effect (<codeph>PDT</codeph>), the UTC time is 7 hours ahead of the local California
+ time; while when daylight savings is not in effect (<codeph>PST</codeph>), the UTC
+ time is 8 hours ahead of the local California time.
</p>
<codeblock>
select now() as local_datetime,
@@ -1083,15 +1392,15 @@ select '2016-01-05' as local_datetime,
<dlentry id="hour">
<dt>
- <codeph>hour(timestamp date)</codeph>
+ HOUR(TIMESTAMP ts)
</dt>
<dd>
- <indexterm audience="hidden">hour() function</indexterm>
<b>Purpose:</b> Returns the hour field from a <codeph>TIMESTAMP</codeph> field.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now, hour(now()) as current_hour;
@@ -1116,16 +1425,15 @@ select now() + interval 12 hours as 12_hours_from_now,
<dlentry rev="1.3.0" id="hours_add">
<dt>
- <codeph>hours_add(timestamp date, int hours)</codeph>, <codeph>hours_add(timestamp date, bigint
- hours)</codeph>
+ HOURS_ADD(TIMESTAMP date, INT hours), HOURS_ADD(TIMESTAMP date, BIGINT hours)
</dt>
<dd>
- <indexterm audience="hidden">hours_add() function</indexterm>
<b>Purpose:</b> Returns the specified date and time plus some number of hours.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now,
@@ -1143,16 +1451,15 @@ select now() as right_now,
<dlentry rev="1.3.0" id="hours_sub">
<dt>
- <codeph>hours_sub(timestamp date, int hours)</codeph>, <codeph>hours_sub(timestamp date, bigint
- hours)</codeph>
+ HOURS_SUB(TIMESTAMP date, INT hours), HOURS_SUB(TIMESTAMP date, BIGINT hours)
</dt>
<dd>
- <indexterm audience="hidden">hours_sub() function</indexterm>
<b>Purpose:</b> Returns the specified date and time minus some number of hours.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now,
@@ -1170,39 +1477,47 @@ select now() as right_now,
<dlentry rev="2.3.0" id="int_months_between">
<dt>
- <codeph>int_months_between(timestamp newer, timestamp older)</codeph>
+ INT_MONTHS_BETWEEN(TIMESTAMP newer, TIMESTAMP older)
</dt>
<dd>
- <indexterm audience="hidden">int_months_between() function</indexterm>
- <b>Purpose:</b> Returns the number of months between the date portions of two <codeph>TIMESTAMP</codeph> values,
- as an <codeph>INT</codeph> representing only the full months that passed.
+ <b>Purpose:</b> Returns the number of months between the date portions of two
+ <codeph>TIMESTAMP</codeph> values, as an <codeph>INT</codeph> representing only the
+ full months that passed.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Typically used in business contexts, for example to determine whether
- a specified number of months have passed or whether some end-of-month deadline was reached.
+ Typically used in business contexts, for example to determine whether a specified
+ number of months have passed or whether some end-of-month deadline was reached.
</p>
+
<p>
- The method of determining the number of elapsed months includes some special handling of
- months with different numbers of days that creates edge cases for dates between the
- 28th and 31st days of certain months. See <codeph>months_between()</codeph> for details.
- The <codeph>int_months_between()</codeph> result is essentially the <codeph>floor()</codeph>
- of the <codeph>months_between()</codeph> result.
+ The method of determining the number of elapsed months includes some special
+ handling of months with different numbers of days that creates edge cases for dates
+ between the 28th and 31st days of certain months. See
+ <codeph>MONTHS_BETWEEN()</codeph> for details. The
+ <codeph>INT_MONTHS_BETWEEN()</codeph> result is essentially the
+ <codeph>FLOOR()</codeph> of the <codeph>MONTHS_BETWEEN()</codeph> result.
</p>
+
<p>
- If either value is <codeph>NULL</codeph>, which could happen for example when converting a
- nonexistent date string such as <codeph>'2015-02-29'</codeph> to a <codeph>TIMESTAMP</codeph>,
- the result is also <codeph>NULL</codeph>.
+ If either value is <codeph>NULL</codeph>, which could happen for example when
+ converting a nonexistent date string such as <codeph>'2015-02-29'</codeph> to a
+ <codeph>TIMESTAMP</codeph>, the result is also <codeph>NULL</codeph>.
</p>
+
<p>
- If the first argument represents an earlier time than the second argument, the result is negative.
+ If the first argument represents an earlier time than the second argument, the
+ result is negative.
</p>
- <p conref="../shared/impala_common.xml#common/example_blurb"/>
+ <p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>/* Less than a full month = 0. */
select int_months_between('2015-02-28', '2015-01-29');
+------------------------------------------------+
@@ -1250,19 +1565,20 @@ select int_months_between('2015-03-31', '2015-01-30');
<dlentry id="last_day" rev="2.9.0 IMPALA-5316">
<dt>
- <codeph>last_day(timestamp t)</codeph>
+ LAST_DAY(TIMESTAMP ts)
</dt>
<dd>
- <indexterm audience="hidden">last_day() function</indexterm>
- <b>Purpose:</b> Returns a <codeph>TIMESTAMP</codeph> corresponding to
- the beginning of the last calendar day in the same month as the
- <codeph>TIMESTAMP</codeph> argument.
+ <b>Purpose:</b> Returns a <codeph>TIMESTAMP</codeph> corresponding to the beginning of
+ the last calendar day in the same month as the <codeph>TIMESTAMP</codeph> argument.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_290"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
If the input argument does not represent a valid Impala <codeph>TIMESTAMP</codeph>
including both date and time portions, the function returns <codeph>NULL</codeph>.
@@ -1271,10 +1587,13 @@ select int_months_between('2015-03-31', '2015-01-30');
allowed range for Impala <codeph>TIMESTAMP</codeph> values, the function returns
<codeph>NULL</codeph>.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
The following example shows how to examine the current date, and dates around the
- end of the month, as <codeph>TIMESTAMP</codeph> values with any time portion removed:
+ end of the month, as <codeph>TIMESTAMP</codeph> values with any time portion
+ removed:
</p>
<codeblock>
select
@@ -1289,8 +1608,8 @@ select
+-------------------------------+---------------------+---------------------+---------------------+
</codeblock>
<p>
- The following example shows how to examine the current date and dates around the
- end of the month as integers representing the day of the month:
+ The following example shows how to examine the current date and dates around the end
+ of the month as integers representing the day of the month:
</p>
<codeblock>
select
@@ -1312,16 +1631,16 @@ select
<dlentry rev="1.3.0" id="microseconds_add">
<dt>
- <codeph>microseconds_add(timestamp date, int microseconds)</codeph>, <codeph>microseconds_add(timestamp
- date, bigint microseconds)</codeph>
+ MICROSECONDS_ADD(TIMESTAMP date, INT microseconds), MICROSECONDS_ADD(TIMESTAMP date,
+ BIGINT microseconds)
</dt>
<dd>
- <indexterm audience="hidden">microseconds_add() function</indexterm>
<b>Purpose:</b> Returns the specified date and time plus some number of microseconds.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now,
@@ -1339,16 +1658,16 @@ select now() as right_now,
<dlentry rev="1.3.0" id="microseconds_sub">
<dt>
- <codeph>microseconds_sub(timestamp date, int microseconds)</codeph>, <codeph>microseconds_sub(timestamp
- date, bigint microseconds)</codeph>
+ MICROSECONDS_SUB(TIMESTAMP date, INT microseconds), MICROSECONDS_SUB(TIMESTAMP date,
+ BIGINT microseconds)
</dt>
<dd>
- <indexterm audience="hidden">microseconds_sub() function</indexterm>
<b>Purpose:</b> Returns the specified date and time minus some number of microseconds.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now,
@@ -1366,21 +1685,24 @@ select now() as right_now,
<dlentry rev="IMPALA-1772 2.6.0" id="millisecond">
<dt>
- <codeph>millisecond(timestamp)</codeph>
+ MILLISECOND(TIMESTAMP ts)
</dt>
<dd>
- <indexterm audience="hidden">millisecond() function</indexterm>
<b>Purpose:</b> Returns the millisecond portion of a <codeph>TIMESTAMP</codeph> value.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_250"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
The millisecond value is truncated, not rounded, if the <codeph>TIMESTAMP</codeph>
value contains more than 3 significant digits to the right of the decimal point.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
252.4 milliseconds truncated to 252.
@@ -1408,16 +1730,16 @@ select now(), millisecond(now());
<dlentry rev="1.3.0" id="milliseconds_add">
<dt>
- <codeph>milliseconds_add(timestamp date, int milliseconds)</codeph>, <codeph>milliseconds_add(timestamp
- date, bigint milliseconds)</codeph>
+ MILLISECONDS_ADD(TIMESTAMP date, INT milliseconds), MILLISECONDS_ADD(TIMESTAMP date,
+ BIGINT milliseconds)
</dt>
<dd>
- <indexterm audience="hidden">milliseconds_add() function</indexterm>
<b>Purpose:</b> Returns the specified date and time plus some number of milliseconds.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now,
@@ -1435,16 +1757,16 @@ select now() as right_now,
<dlentry rev="1.3.0" id="milliseconds_sub">
<dt>
- <codeph>milliseconds_sub(timestamp date, int milliseconds)</codeph>, <codeph>milliseconds_sub(timestamp
- date, bigint milliseconds)</codeph>
+ MILLISECONDS_SUB(TIMESTAMP date, INT milliseconds), MILLISECONDS_SUB(TIMESTAMP date,
+ BIGINT milliseconds)
</dt>
<dd>
- <indexterm audience="hidden">milliseconds_sub() function</indexterm>
<b>Purpose:</b> Returns the specified date and time minus some number of milliseconds.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now,
@@ -1462,15 +1784,15 @@ select now() as right_now,
<dlentry id="minute">
<dt>
- <codeph>minute(timestamp date)</codeph>
+ MINUTE(TIMESTAMP date)
</dt>
<dd>
- <indexterm audience="hidden">minute() function</indexterm>
<b>Purpose:</b> Returns the minute field from a <codeph>TIMESTAMP</codeph> value.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now, minute(now()) as current_minute;
@@ -1487,16 +1809,15 @@ select now() as right_now, minute(now()) as current_minute;
<dlentry rev="1.3.0" id="minutes_add">
<dt>
- <codeph>minutes_add(timestamp date, int minutes)</codeph>, <codeph>minutes_add(timestamp date, bigint
- minutes)</codeph>
+ MINUTES_ADD(TIMESTAMP date, INT minutes), MINUTES_ADD(TIMESTAMP date, BIGINT minutes)
</dt>
<dd>
- <indexterm audience="hidden">minutes_add() function</indexterm>
<b>Purpose:</b> Returns the specified date and time plus some number of minutes.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now, minutes_add(now(), 90) as 90_minutes_from_now;
@@ -1513,16 +1834,15 @@ select now() as right_now, minutes_add(now(), 90) as 90_minutes_from_now;
<dlentry rev="1.3.0" id="minutes_sub">
<dt>
- <codeph>minutes_sub(timestamp date, int minutes)</codeph>, <codeph>minutes_sub(timestamp date, bigint
- minutes)</codeph>
+ MINUTES_SUB(TIMESTAMP date, INT minutes), MINUTES_SUB(TIMESTAMP date, BIGINT minutes)
</dt>
<dd>
- <indexterm audience="hidden">minutes_sub() function</indexterm>
<b>Purpose:</b> Returns the specified date and time minus some number of minutes.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now, minutes_sub(now(), 90) as 90_minutes_ago;
@@ -1539,15 +1859,16 @@ select now() as right_now, minutes_sub(now(), 90) as 90_minutes_ago;
<dlentry id="month">
<dt>
- <codeph>month(timestamp date)</codeph>
+ MONTH(TIMESTAMP date)
</dt>
<dd>
- <indexterm audience="hidden">month() function</indexterm>
- <b>Purpose:</b> Returns the month field, represented as an integer, from the date portion of a <codeph>TIMESTAMP</codeph>.
+ <b>Purpose:</b> Returns the month field, represented as an integer, from the date
+ portion of a <codeph>TIMESTAMP</codeph>.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
select now() as right_now, month(now()) as current_month;
@@ -1560,40 +1881,42 @@ select now() as right_now, month(now()) as current_month;
</dd>
</dlentry>
+
<dlentry id="monthname">
+
<dt>
- <codeph>monthname(timestamp date)</codeph>
+ MONTHNAME(TIMESTAMP date)
</dt>
+
<dd>
- <b>Purpose:</b> Returns the month field from a
- <codeph>TIMESTAMP</codeph> value, converted to the string
- corresponding to that month name.
+ <b>Purpose:</b> Returns the month field from a <codeph>TIMESTAMP</codeph> value,
+ converted to the string corresponding to that month name.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
+
</dlentry>
<dlentry rev="1.3.0" id="months_add">
<dt>
- <codeph>months_add(timestamp date, int months)</codeph>, <codeph>months_add(timestamp date, bigint
- months)</codeph>
+ MONTHS_ADD(TIMESTAMP date, INT months), MONTHS_ADD(TIMESTAMP date, BIGINT months)
</dt>
<dd>
- <indexterm audience="hidden">months_add() function</indexterm>
<b>Purpose:</b> Returns the specified date and time plus some number of months.
<p>
- <b>Return type:</b> <codeph>timestamp</codeph>
+ <b>Return type:</b> <codeph>TIMESTAMP</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following example shows the effects of adding some number of
- months to a <codeph>TIMESTAMP</codeph> value, using both the
- <codeph>months_add()</codeph> function and its <codeph>add_months()</codeph>
- alias. These examples use <codeph>trunc()</codeph> to strip off the time portion
- and leave just the date.
+ The following example shows the effects of adding some number of months to a
+ <codeph>TIMESTAMP</codeph> value, using both the <codeph>MONTHS_ADD()</codeph>
+ function and its <codeph>ADD_MONTHS()</codeph> alias. These examples use
+ <codeph>TRUNC()</codeph> to strip off the time portion and leave just the date.
</p>
<codeblock>
with t1 as (select trunc(now(), 'dd') as today)
@@ -1613,12 +1936,12 @@ with t1 as (select trunc(now(), 'dd') as today)
+---------------------+---------------------+
</codeblock>
<p>
- The following examples show how if <codeph>months_add()</codeph>
- would return a nonexistent date, due to different months having
- different numbers of days, the function returns a <codeph>TIMESTAMP</codeph>
- from the last day of the relevant month. For example, adding one month
- to January 31 produces a date of February 29th in the year 2016 (a leap year),
- and February 28th in the year 2015 (a non-leap year).
+ The following examples show how if <codeph>MONTHS_ADD()</codeph> would return a
+ nonexistent date, due to different months having different numbers of days, the
+ function returns a <codeph>TIMESTAMP</codeph> from the last day of the relevant
+ month. For example, adding one month to January 31 produces a date of February 29th
+ in the year 2016 (a leap year), and February 28th in the year 2015 (a non-leap
+ year).
</p>
<codeblock>
with t1 as (select cast('2016-01-31' as timestamp) as jan_31)
@@ -1644,45 +1967,55 @@ with t1 as (select cast('2015-01-31' as timestamp) as jan_31)
<dlentry rev="2.3.0" id="months_between">
<dt>
- <codeph>months_between(timestamp newer, timestamp older)</codeph>
+ MONTHS_BETWEEN(TIMESTAMP newer, TIMESTAMP older)
</dt>
<dd>
- <indexterm audience="hidden">months_between() function</indexterm>
- <b>Purpose:</b> Returns the number of months between the date portions of two <codeph>TIMESTAMP</codeph> values.
- Can include a fractional part representing extra days in addition to the full months
- between the dates. The fractional component is computed by dividing the difference in days by 31 (regardless of the month).
+ <b>Purpose:</b> Returns the number of months between the date portions of two
+ <codeph>TIMESTAMP</codeph> values. Can include a fractional part representing extra
+ days in addition to the full months between the dates. The fractional component is
+ computed by dividing the difference in days by 31 (regardless of the month).
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Typically used in business contexts, for example to determine whether
- a specified number of months have passed or whether some end-of-month deadline was reached.
+ Typically used in business contexts, for example to determine whether a specified
+ number of months have passed or whether some end-of-month deadline was reached.
</p>
+
<p>
If the only consideration is the number of full months and any fractional value is
- not significant, use <codeph>int_months_between()</codeph> instead.
+ not significant, use <codeph>INT_MONTHS_BETWEEN()</codeph> instead.
</p>
+
<p>
- The method of determining the number of elapsed months includes some special handling of
- months with different numbers of days that creates edge cases for dates between the
- 28th and 31st days of certain months.
+ The method of determining the number of elapsed months includes some special
+ handling of months with different numbers of days that creates edge cases for dates
+ between the 28th and 31st days of certain months.
</p>
+
<p>
- If either value is <codeph>NULL</codeph>, which could happen for example when converting a
- nonexistent date string such as <codeph>'2015-02-29'</codeph> to a <codeph>TIMESTAMP</codeph>,
- the result is also <codeph>NULL</codeph>.
+ If either value is <codeph>NULL</codeph>, which could happen for example when
+ converting a nonexistent date string such as <codeph>'2015-02-29'</codeph> to a
+ <codeph>TIMESTAMP</codeph>, the result is also <codeph>NULL</codeph>.
</p>
+
<p>
- If the first argument represents an earlier time than the second argument, the result is negative.
+ If the first argument represents an earlier time than the second argument, the
+ result is negative.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show how dates that are on the same day of the month
- are considered to be exactly N months apart, even if the months have different
- numbers of days.
+ The following examples show how dates that are on the same day of the month are
+ considered to be exactly N months apart, even if the months have different numbers
+ of days.
</p>
<codeblock>select months_between('2015-02-28', '2015-01-28');
+--------------------------------------------+
@@ -1706,12 +2039,12 @@ select months_between(now() + interval 1 year, now());
+------------------------------------------------+
</codeblock>
<p>
- The following examples show how dates that are on the last day of the month
- are considered to be exactly N months apart, even if the months have different
- numbers of days. For example, from January 28th to February 28th is exactly one
- month because the day of the month is identical; January 31st to February 28th
- is exactly one month because in both cases it is the last day of the month;
- but January 29th or 30th to February 28th is considered a fractional month.
+ The following examples show how dates that are on the last day of the month are
+ considered to be exactly N months apart, even if the months have different numbers
+ of days. For example, from January 28th to
<TRUNCATED>
[08/10] impala git commit: IMPALA-7682: Make AuthorizationPolicy
thread-safe
Posted by mi...@apache.org.
IMPALA-7682: Make AuthorizationPolicy thread-safe
This patch makes AuthorizationPolicy thread-safe by making
AuthorizationPolicy::listPrivileges(Set<String> groups,
Set<String> users, ActiveRoleSet roleSet) synchronized.
Change-Id: I28c516c0ab3e48ab4284084afd7149ed1a3c6cb2
Reviewed-on: http://gerrit.cloudera.org:8080/11644
Reviewed-by: Impala Public Jenkins <im...@cloudera.com>
Tested-by: Impala Public Jenkins <im...@cloudera.com>
Project: http://git-wip-us.apache.org/repos/asf/impala/repo
Commit: http://git-wip-us.apache.org/repos/asf/impala/commit/6099255f
Tree: http://git-wip-us.apache.org/repos/asf/impala/tree/6099255f
Diff: http://git-wip-us.apache.org/repos/asf/impala/diff/6099255f
Branch: refs/heads/master
Commit: 6099255fa69d41c5f3dd581a976fd5be3b027f0a
Parents: e8ee827
Author: Fredy Wijaya <fw...@cloudera.com>
Authored: Tue Oct 9 21:04:15 2018 -0700
Committer: Impala Public Jenkins <im...@cloudera.com>
Committed: Wed Oct 10 23:06:45 2018 +0000
----------------------------------------------------------------------
.../main/java/org/apache/impala/catalog/AuthorizationPolicy.java | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/impala/blob/6099255f/fe/src/main/java/org/apache/impala/catalog/AuthorizationPolicy.java
----------------------------------------------------------------------
diff --git a/fe/src/main/java/org/apache/impala/catalog/AuthorizationPolicy.java b/fe/src/main/java/org/apache/impala/catalog/AuthorizationPolicy.java
index 4819079..f810d15 100644
--- a/fe/src/main/java/org/apache/impala/catalog/AuthorizationPolicy.java
+++ b/fe/src/main/java/org/apache/impala/catalog/AuthorizationPolicy.java
@@ -437,7 +437,7 @@ public class AuthorizationPolicy implements PrivilegeCache {
* Returns a set of privilege strings in Sentry format.
*/
@Override
- public Set<String> listPrivileges(Set<String> groups, Set<String> users,
+ public synchronized Set<String> listPrivileges(Set<String> groups, Set<String> users,
ActiveRoleSet roleSet) {
Set<String> privileges = listPrivileges(groups, roleSet);
for (String userName: users) {
[03/10] impala git commit: [DOCS] Built-in Functions doc format
Changes
Posted by mi...@apache.org.
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_math_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_math_functions.xml b/docs/topics/impala_math_functions.xml
index b4f97c5..e4eb224 100644
--- a/docs/topics/impala_math_functions.xml
+++ b/docs/topics/impala_math_functions.xml
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?><!--
+<?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
@@ -20,7 +21,13 @@ under the License.
<concept id="math_functions">
<title>Impala Mathematical Functions</title>
- <titlealts audience="PDF"><navtitle>Mathematical Functions</navtitle></titlealts>
+
+ <titlealts audience="PDF">
+
+ <navtitle>Mathematical Functions</navtitle>
+
+ </titlealts>
+
<prolog>
<metadata>
<data name="Category" value="Impala"/>
@@ -35,29 +42,32 @@ under the License.
<conbody>
<p>
- Mathematical functions, or arithmetic functions, perform numeric calculations that are typically more complex
- than basic addition, subtraction, multiplication, and division. For example, these functions include
- trigonometric, logarithmic, and base conversion operations.
+ Mathematical functions, or arithmetic functions, perform numeric calculations that are
+ typically more complex than basic addition, subtraction, multiplication, and division. For
+ example, these functions include trigonometric, logarithmic, and base conversion
+ operations.
</p>
<note>
- In Impala, exponentiation uses the <codeph>pow()</codeph> function rather than an exponentiation operator
- such as <codeph>**</codeph>.
+ In Impala, exponentiation uses the <codeph>pow()</codeph> function rather than an
+ exponentiation operator such as <codeph>**</codeph>.
</note>
<p conref="../shared/impala_common.xml#common/related_info"/>
<p>
- The mathematical functions operate mainly on these data types: <xref href="impala_int.xml#int"/>,
- <xref href="impala_bigint.xml#bigint"/>, <xref href="impala_smallint.xml#smallint"/>,
- <xref href="impala_tinyint.xml#tinyint"/>, <xref href="impala_double.xml#double"/>,
- <xref href="impala_float.xml#float"/>, and <xref href="impala_decimal.xml#decimal"/>. For the operators that
- perform the standard operations such as addition, subtraction, multiplication, and division, see
+ The mathematical functions operate mainly on these data types:
+ <xref href="impala_int.xml#int"/>, <xref href="impala_bigint.xml#bigint"/>,
+ <xref href="impala_smallint.xml#smallint"/>, <xref href="impala_tinyint.xml#tinyint"/>,
+ <xref href="impala_double.xml#double"/>, <xref href="impala_float.xml#float"/>, and
+ <xref href="impala_decimal.xml#decimal"/>. For the operators that perform the standard
+ operations such as addition, subtraction, multiplication, and division, see
<xref href="impala_operators.xml#arithmetic_operators"/>.
</p>
<p>
- Functions that perform bitwise operations are explained in <xref href="impala_bit_functions.xml#bit_functions"/>.
+ Functions that perform bitwise operations are explained in
+ <xref href="impala_bit_functions.xml#bit_functions"/>.
</p>
<p>
@@ -68,22 +78,231 @@ under the License.
Impala supports the following mathematical functions:
</p>
+ <ul>
+ <li>
+ <xref href="#math_functions/abs">ABS</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/acos">ACOS</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/asin">ASIN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/atan">ATAN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/atan2">ATAN2</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/bin">BIN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/ceil">CEIL, CEILING, DCEIL</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/conv">CONV</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/cos">COS</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/cosh">COSH</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/cot">COT</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/degrees">DEGREES</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/e">E</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/exp">EXP</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/factorial">FACTORIAL</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/floor">FLOOR, DFLOOR</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/fmod">FMOD</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/fnv_hash">FNV_HASH</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/greatest">GREATEST</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/hex">HEX</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/is_inf">IS_INF</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/is_nan">IS_NAN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/least">LEAST</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/ln">LN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/log">LOG</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/log10">LOG10</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/log2">LOG2</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/max_int">MAX_INT, MAX_TINYINT, MAX_SMALLINT,
+ MAX_BIGINT</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/min_int">MIN_INT, MIN_TINYINT, MIN_SMALLINT,
+ MIN_BIGINT</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/mod">MOD</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/murmur_hash">MURMUR_HASH</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/negative">NEGATIVE</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/pi">PI</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/pmod">PMOD</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/positive">POSITIVE</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/pow">POW, POWER, DPOW, FPOW</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/precision">PRECISION</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/quotient">QUOTIENT</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/radians">RADIANS</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/rand">RAND, RANDOM</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/round">ROUND, DROUND</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/scale">SCALE</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/sign">SIGN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/sin">SIN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/sinh">SINH</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/sqrt">SQRT</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/tan">TAN</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/tanh">TANH</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/truncate">TRUNCATE, DTRUNC, TRUNC</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/unhex">UNHEX</xref>
+ </li>
+
+ <li>
+ <xref href="#math_functions/width_bucket">WIDTH_BUCKET</xref>
+ </li>
+ </ul>
+
<dl>
<dlentry rev="1.4.0" id="abs">
<dt rev="1.4.0 2.0.1">
- <codeph>abs(numeric_type a)</codeph>
-<!-- <codeph>abs(double a), abs(decimal(p,s) a)</codeph> -->
+ ABS(numeric_type a)
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">abs() function</indexterm>
<b>Purpose:</b> Returns the absolute value of the argument.
- <p rev="2.0.1" conref="../shared/impala_common.xml#common/return_type_same"/>
+ <p
+ rev="2.0.1"
+ conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p>
- <b>Usage notes:</b> Use this function to ensure all return values are positive. This is different than
- the <codeph>positive()</codeph> function, which returns its argument unchanged (even if the argument
- was negative).
+ <b>Usage notes:</b> Use this function to ensure all return values are positive. This
+ is different than the <codeph>POSITIVE()</codeph> function, which returns its
+ argument unchanged (even if the argument was negative).
</p>
</dd>
@@ -92,14 +311,13 @@ under the License.
<dlentry id="acos">
<dt>
- <codeph>acos(double a)</codeph>
+ ACOS(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">acos() function</indexterm>
<b>Purpose:</b> Returns the arccosine of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -108,14 +326,13 @@ under the License.
<dlentry id="asin">
<dt>
- <codeph>asin(double a)</codeph>
+ ASIN(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">asin() function</indexterm>
<b>Purpose:</b> Returns the arcsine of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -124,14 +341,13 @@ under the License.
<dlentry id="atan">
<dt>
- <codeph>atan(double a)</codeph>
+ ATAN(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">atan() function</indexterm>
<b>Purpose:</b> Returns the arctangent of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -140,15 +356,14 @@ under the License.
<dlentry id="atan2" rev="2.3.0 IMPALA-1771">
<dt rev="2.3.0 IMPALA-1771">
- <codeph>atan2(double a, double b)</codeph>
+ ATAN2(DOUBLE a, DOUBLE b)
</dt>
<dd rev="2.3.0 IMPALA-1771">
- <indexterm audience="hidden">atan2() function</indexterm>
- <b>Purpose:</b> Returns the arctangent of the two arguments, with the signs of the arguments used to determine the
- quadrant of the result.
+ <b>Purpose:</b> Returns the arctangent of the two arguments, with the signs of the
+ arguments used to determine the quadrant of the result.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -157,15 +372,14 @@ under the License.
<dlentry id="bin">
<dt>
- <codeph>bin(bigint a)</codeph>
+ BIN(BIGINT a)
</dt>
<dd>
- <indexterm audience="hidden">bin() function</indexterm>
- <b>Purpose:</b> Returns the binary representation of an integer value, that is, a string of 0 and 1
- digits.
+ <b>Purpose:</b> Returns the binary representation of an integer value, that is, a
+ string of 0 and 1 digits.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -174,17 +388,13 @@ under the License.
<dlentry rev="1.4.0" id="ceil">
<dt rev="1.4.0">
- <codeph>ceil(double a)</codeph>,
- <codeph>ceil(decimal(p,s) a)</codeph>,
- <codeph id="ceiling">ceiling(double a)</codeph>,
- <codeph>ceiling(decimal(p,s) a)</codeph>,
- <codeph id="dceil" rev="2.3.0">dceil(double a)</codeph>,
- <codeph rev="2.3.0">dceil(decimal(p,s) a)</codeph>
+ CEIL(DOUBLE a), CEIL(DECIMAL(p,s) a), CEILING(DOUBLE a), CEILING(DECIMAL(p,s) a),
+ DCEIL(DOUBLE a), DCEIL(DECIMAL(p,s) a)
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">ceil() function</indexterm>
- <b>Purpose:</b> Returns the smallest integer that is greater than or equal to the argument.
+ <b>Purpose:</b> Returns the smallest integer that is greater than or equal to the
+ argument.
<p>
<b>Return type:</b> Same as the input value
</p>
@@ -195,72 +405,104 @@ under the License.
<dlentry id="conv">
<dt>
- <codeph>conv(bigint n, int from_base, int to_base), conv(string s, int
- from_base, int to_base)</codeph>
+ CONV(BIGINT n, INT from_base, INT to_base), CONV(STRING s, INT from_base, INT to_base)
</dt>
<dd>
- <b>Purpose:</b> Returns a string representation of the first argument
- converted from <codeph>from_base</codeph> to <codeph>to_base</codeph>.
- The first argument can be specified as a number or a string. For
- example, <codeph>conv(100, 2, 10)</codeph> and <codeph>conv('100', 2,
- 10)</codeph> both return <codeph>'4'</codeph>. <p>
- <b>Return type:</b>
- <codeph>string</codeph>
+ <b>Purpose:</b> Returns a string representation of the first argument converted from
+ <codeph>from_base</codeph> to <codeph>to_base</codeph>. The first argument can be
+ specified as a number or a string. For example, <codeph>CONV(100, 2, 10)</codeph> and
+ <codeph>CONV('100', 2, 10)</codeph> both return <codeph>'4'</codeph>.
+ <p>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p>
<b>Usage notes:</b>
</p>
- <p> If <codeph>to_base</codeph> is negative, the first argument is
- treated as signed, and otherwise, it is treated as unsigned. For
- example: </p>
+
+ <p>
+ If <codeph>to_base</codeph> is negative, the first argument is treated as signed,
+ and otherwise, it is treated as unsigned. For example:
+ </p>
<ul>
<li>
- <codeph>conv(-17, 10, -2) </codeph>returns
- <codeph>'-10001'</codeph>,<codeph> -17</codeph> in base 2. </li>
+ <codeph>conv(-17, 10, -2) </codeph>returns <codeph>'-10001'</codeph>,<codeph>
+ -17</codeph> in base 2.
+ </li>
+
<li>
<codeph>conv(-17, 10, 10)</codeph> returns
- <codeph>'18446744073709551599'</codeph>. <codeph>-17</codeph> is
- interpreted as an unsigned, 2^64-17, and then the value is
- returned in base 10.</li>
- </ul><p>The function returns <codeph>NULL</codeph> when the following
- illegal arguments are specified: </p>
+ <codeph>'18446744073709551599'</codeph>. <codeph>-17</codeph> is interpreted as an
+ unsigned, 2^64-17, and then the value is returned in base 10.
+ </li>
+ </ul>
+ <p>
+ The function returns <codeph>NULL</codeph> when the following illegal arguments are
+ specified:
+ </p>
<ul>
- <li> Any argument is <codeph>NULL</codeph>. </li>
+ <li>
+ Any argument is <codeph>NULL</codeph>.
+ </li>
+
<li>
<codeph>from_base</codeph> or <codeph>to_base</codeph> is below
- <codeph>-36</codeph> or above <codeph>36</codeph>. </li>
+ <codeph>-36</codeph> or above <codeph>36</codeph>.
+ </li>
+
<li>
- <codeph>from_base</codeph> or <codeph>to_base</codeph> is
- <codeph>-1</codeph>, <codeph>0</codeph>, or <codeph>1</codeph>. </li>
- <li> The first argument represents a positive number and
- <codeph>from_base</codeph> is a negative number.</li>
+ <codeph>from_base</codeph> or <codeph>to_base</codeph> is <codeph>-1</codeph>,
+ <codeph>0</codeph>, or <codeph>1</codeph>.
+ </li>
+
+ <li>
+ The first argument represents a positive number and <codeph>from_base</codeph> is
+ a negative number.
+ </li>
</ul>
- <p>If the first argument represents a negative number and
- <codeph>from_base</codeph> is a negative number, the function
- returns <codeph>0</codeph>.</p><p> If the first argument represents
- a number larger than the maximum <codeph>bigint</codeph>, the
- function returns: </p>
+ <p>
+ If the first argument represents a negative number and <codeph>from_base</codeph> is
+ a negative number, the function returns <codeph>0</codeph>.
+ </p>
+
+ <p>
+ If the first argument represents a number larger than the maximum
+ <codeph>bigint</codeph>, the function returns:
+ </p>
<ul>
- <li> The string representation of -1 in <codeph>to_base</codeph> if
- <codeph>to_base</codeph> is negative. </li>
- <li> The string representation of 18446744073709551615' (2^64 - 1)
- in <codeph>to_base</codeph> if <codeph>to_base</codeph> is
- positive.</li>
+ <li>
+ The string representation of -1 in <codeph>to_base</codeph> if
+ <codeph>to_base</codeph> is negative.
+ </li>
+
+ <li>
+ The string representation of 18446744073709551615' (2^64 - 1) in
+ <codeph>to_base</codeph> if <codeph>to_base</codeph> is positive.
+ </li>
</ul>
- <p> If the first argument does not represent a valid number in
- <codeph>from_base</codeph>, e.g. 3 in base 2 or '1a23' in base 10,
- the digits in the first argument are evaluated from left-to-right
- and used if a valid digit in <codeph>from_base</codeph>. The invalid
- digit and the digits to the right are ignored. </p>
- <p> For example:<ul>
- <li><codeph> conv(445, 5, 10)</codeph> is converted to
- <codeph>conv(44, 5, 10)</codeph> and returns
- <codeph>'24'</codeph>. </li>
- <li><codeph> conv('1a23', 10, 16)</codeph> is converted to
- <codeph>conv('1', 10 , 16)</codeph> and returns
- <codeph>'1'</codeph>. </li>
- </ul></p>
+ <p>
+ If the first argument does not represent a valid number in
+ <codeph>from_base</codeph>, e.g. 3 in base 2 or '1a23' in base 10, the digits in the
+ first argument are evaluated from left-to-right and used if a valid digit in
+ <codeph>from_base</codeph>. The invalid digit and the digits to the right are
+ ignored.
+ </p>
+
+ <p>
+ For example:
+ <ul>
+ <li>
+ <codeph> conv(445, 5, 10)</codeph> is converted to <codeph>conv(44, 5,
+ 10)</codeph> and returns <codeph>'24'</codeph>.
+ </li>
+
+ <li>
+ <codeph> conv('1a23', 10, 16)</codeph> is converted to <codeph>conv('1', 10 ,
+ 16)</codeph> and returns <codeph>'1'</codeph>.
+ </li>
+ </ul>
+ </p>
</dd>
</dlentry>
@@ -268,14 +510,13 @@ under the License.
<dlentry id="cos">
<dt>
- <codeph>cos(double a)</codeph>
+ COS(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">cos() function</indexterm>
<b>Purpose:</b> Returns the cosine of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -284,14 +525,13 @@ under the License.
<dlentry id="cosh" rev="2.3.0 IMPALA-1771">
<dt rev="2.3.0 IMPALA-1771">
- <codeph>cosh(double a)</codeph>
+ COSH(DOUBLE a)
</dt>
<dd rev="2.3.0 IMPALA-1771">
- <indexterm audience="hidden">cosh() function</indexterm>
<b>Purpose:</b> Returns the hyperbolic cosine of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -300,15 +540,15 @@ under the License.
<dlentry id="cot" rev="2.3.0 IMPALA-1771">
<dt rev="2.3.0 IMPALA-1771">
- <codeph>cot(double a)</codeph>
+ COT(DOUBLE a)
</dt>
<dd rev="2.3.0 IMPALA-1771">
- <indexterm audience="hidden">cot() function</indexterm>
<b>Purpose:</b> Returns the cotangent of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
</dd>
@@ -317,14 +557,13 @@ under the License.
<dlentry id="degrees">
<dt>
- <codeph>degrees(double a)</codeph>
+ DEGREES(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">degrees() function</indexterm>
<b>Purpose:</b> Converts argument value from radians to degrees.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -333,16 +572,17 @@ under the License.
<dlentry id="e">
<dt>
- <codeph>e()</codeph>
+ E()
</dt>
<dd>
- <indexterm audience="hidden">e() function</indexterm>
<b>Purpose:</b> Returns the
- <xref href="https://en.wikipedia.org/wiki/E_(mathematical_constant" scope="external" format="html">mathematical
+ <xref
+ href="https://en.wikipedia.org/wiki/E_(mathematical_constant"
+ scope="external" format="html">mathematical
constant e</xref>.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -351,17 +591,17 @@ under the License.
<dlentry id="exp">
<dt>
- <codeph>exp(double a)</codeph>,
- <codeph rev="2.3.0" id="dexp">dexp(double a)</codeph>
+ EXP(DOUBLE a), DEXP(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">exp() function</indexterm>
<b>Purpose:</b> Returns the
- <xref href="https://en.wikipedia.org/wiki/E_(mathematical_constant" scope="external" format="html">mathematical
+ <xref
+ href="https://en.wikipedia.org/wiki/E_(mathematical_constant"
+ scope="external" format="html">mathematical
constant e</xref> raised to the power of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -370,22 +610,30 @@ under the License.
<dlentry rev="2.3.0" id="factorial">
<dt rev="2.3.0">
- <codeph>factorial(integer_type a)</codeph>
+ FACTORIAL(integer_type a)
</dt>
+
<dd rev="2.3.0">
- <indexterm audience="hidden">factorial() function</indexterm>
- <b>Purpose:</b> Computes the <xref href="https://en.wikipedia.org/wiki/Factorial" scope="external" format="html">factorial</xref> of an integer value.
- It works with any integer type.
- <p conref="../shared/impala_common.xml#common/added_in_230"/>
- <p>
- <b>Usage notes:</b> You can use either the <codeph>factorial()</codeph> function or the <codeph>!</codeph> operator.
- The factorial of 0 is 1. Likewise, the <codeph>factorial()</codeph> function returns 1 for any negative value.
- The maximum positive value for the input argument is 20; a value of 21 or greater overflows the
+ <b>Purpose:</b> Computes the
+ <xref
+ href="https://en.wikipedia.org/wiki/Factorial" scope="external"
+ format="html">factorial</xref>
+ of an integer value. It works with any integer type.
+ <p
+ conref="../shared/impala_common.xml#common/added_in_230"/>
+
+ <p>
+ <b>Usage notes:</b> You can use either the <codeph>factorial()</codeph> function or
+ the <codeph>!</codeph> operator. The factorial of 0 is 1. Likewise, the
+ <codeph>factorial()</codeph> function returns 1 for any negative value. The maximum
+ positive value for the input argument is 20; a value of 21 or greater overflows the
range for a <codeph>BIGINT</codeph> and causes an error.
</p>
+
<p>
- <b>Return type:</b> <codeph>bigint</codeph>
+ <b>Return type:</b> <codeph>BIGINT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
<codeblock>select factorial(5);
+--------------+
@@ -422,15 +670,12 @@ select factorial(-100);
<dlentry id="floor">
<dt>
- <codeph>floor(double a)</codeph>,
- <codeph>floor(decimal(p,s) a)</codeph>,
- <codeph rev="2.3.0" id="dfloor">dfloor(double a)</codeph>,
- <codeph rev="2.3.0">dfloor(decimal(p,s) a)</codeph>
+ FLOOR(DOUBLE a), FLOOR(DECIMAL(p,s) a), DFLOOR(DOUBLE a), DFLOOR(DECIMAL(p,s) a)
</dt>
<dd>
- <indexterm audience="hidden">floor() function</indexterm>
- <b>Purpose:</b> Returns the largest integer that is less than or equal to the argument.
+ <b>Purpose:</b> Returns the largest integer that is less than or equal to the
+ argument.
<p>
<b>Return type:</b> Same as the input type
</p>
@@ -441,28 +686,36 @@ select factorial(-100);
<dlentry id="fmod">
<dt>
- <codeph>fmod(double a, double b), fmod(float a, float b)</codeph>
+ FMOD(DOUBLE a, DOUBLE b), FMOD(FLOAT a, FLOAT b)
</dt>
<dd>
- <indexterm audience="hidden">fmod() function</indexterm>
- <b>Purpose:</b> Returns the modulus of a floating-point number.<p>
- <b>Return type:</b>
- <codeph>float</codeph> or <codeph>double</codeph>, depending on type
- of arguments </p>
+ <b>Purpose:</b> Returns the modulus of a floating-point number.
+ <p>
+ <b>Return type:</b> <codeph>FLOAT</codeph> or <codeph>DOUBLE</codeph>, depending on
+ type of arguments
+ </p>
+
<p conref="../shared/impala_common.xml#common/added_in_111"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p> Because this function operates on <codeph>DOUBLE</codeph> or
- <codeph>FLOAT</codeph> values, it is subject to potential rounding
- errors for values that cannot be represented precisely. Prefer to
- use whole numbers, or values that you know can be represented
- precisely by the <codeph>DOUBLE</codeph> or <codeph>FLOAT</codeph>
- types. </p>
+
+ <p>
+ Because this function operates on <codeph>DOUBLE</codeph> or <codeph>FLOAT</codeph>
+ values, it is subject to potential rounding errors for values that cannot be
+ represented precisely. Prefer to use whole numbers, or values that you know can be
+ represented precisely by the <codeph>DOUBLE</codeph> or <codeph>FLOAT</codeph>
+ types.
+ </p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
- <p> The following examples show equivalent operations with the
- <codeph>fmod()</codeph> function and the <codeph>%</codeph>
- arithmetic operator, for values not subject to any rounding error. </p>
- <codeblock>select fmod(10,3);
+
+ <p>
+ The following examples show equivalent operations with the <codeph>fmod()</codeph>
+ function and the <codeph>%</codeph> arithmetic operator, for values not subject to
+ any rounding error.
+ </p>
+<codeblock>select fmod(10,3);
+-------------+
| fmod(10, 3) |
+-------------+
@@ -490,16 +743,16 @@ select 5.5 % 2;
| 1.5 |
+---------+
</codeblock>
- <p> The following examples show operations with the
- <codeph>fmod()</codeph> function for values that cannot be
- represented precisely by the <codeph>DOUBLE</codeph> or
- <codeph>FLOAT</codeph> types, and thus are subject to rounding
- error. <codeph>fmod(9.9,3.0)</codeph> returns a value slightly
- different than the expected 0.9 because of rounding.
- <codeph>fmod(9.9,3.3)</codeph> returns a value quite different
- from the expected value of 0 because of rounding error during
- intermediate calculations. </p>
- <codeblock>select fmod(9.9,3.0);
+ <p>
+ The following examples show operations with the <codeph>fmod()</codeph> function for
+ values that cannot be represented precisely by the <codeph>DOUBLE</codeph> or
+ <codeph>FLOAT</codeph> types, and thus are subject to rounding error.
+ <codeph>fmod(9.9,3.0)</codeph> returns a value slightly different than the expected
+ 0.9 because of rounding. <codeph>fmod(9.9,3.3)</codeph> returns a value quite
+ different from the expected value of 0 because of rounding error during intermediate
+ calculations.
+ </p>
+<codeblock>select fmod(9.9,3.0);
+--------------------+
| fmod(9.9, 3.0) |
+--------------------+
@@ -520,43 +773,53 @@ select fmod(9.9,3.3);
<dlentry rev="1.2.2" id="fnv_hash">
<dt rev="1.2.2">
- <codeph>fnv_hash(type v)</codeph>,
+ FNV_HASH(type v),
</dt>
<dd rev="1.2.2">
- <indexterm audience="hidden">fnv_hash() function</indexterm>
- <b>Purpose:</b> Returns a consistent 64-bit value derived from the input argument, for convenience of
- implementing hashing logic in an application.
+ <b>Purpose:</b> Returns a consistent 64-bit value derived from the input argument, for
+ convenience of implementing hashing logic in an application.
<p>
<b>Return type:</b> <codeph>BIGINT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- You might use the return value in an application where you perform load balancing, bucketing, or some
- other technique to divide processing or storage.
+ You might use the return value in an application where you perform load balancing,
+ bucketing, or some other technique to divide processing or storage.
</p>
+
<p>
- Because the result can be any 64-bit value, to restrict the value to a particular range, you can use an
- expression that includes the <codeph>ABS()</codeph> function and the <codeph>%</codeph> (modulo)
- operator. For example, to produce a hash value in the range 0-9, you could use the expression
- <codeph>ABS(FNV_HASH(x)) % 10</codeph>.
+ Because the result can be any 64-bit value, to restrict the value to a particular
+ range, you can use an expression that includes the <codeph>ABS()</codeph> function
+ and the <codeph>%</codeph> (modulo) operator. For example, to produce a hash value
+ in the range 0-9, you could use the expression <codeph>ABS(FNV_HASH(x)) %
+ 10</codeph>.
</p>
+
<p>
- This function implements the same algorithm that Impala uses internally for hashing, on systems where
- the CRC32 instructions are not available.
+ This function implements the same algorithm that Impala uses internally for hashing,
+ on systems where the CRC32 instructions are not available.
</p>
+
<p>
This function implements the
- <xref href="http://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function" scope="external" format="html">Fowler–Noll–Vo
- hash function</xref>, in particular the FNV-1a variation. This is not a perfect hash function: some
- combinations of values could produce the same result value. It is not suitable for cryptographic use.
+ <xref
+ href="http://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function"
+ scope="external" format="html">Fowler–Noll–Vo
+ hash function</xref>, in particular the FNV-1a variation. This is not a perfect hash
+ function: some combinations of values could produce the same result value. It is not
+ suitable for cryptographic use.
</p>
+
<p>
- Similar input values of different types could produce different hash values, for example the same
- numeric value represented as <codeph>SMALLINT</codeph> or <codeph>BIGINT</codeph>,
- <codeph>FLOAT</codeph> or <codeph>DOUBLE</codeph>, or <codeph>DECIMAL(5,2)</codeph> or
- <codeph>DECIMAL(20,5)</codeph>.
+ Similar input values of different types could produce different hash values, for
+ example the same numeric value represented as <codeph>SMALLINT</codeph> or
+ <codeph>BIGINT</codeph>, <codeph>FLOAT</codeph> or <codeph>DOUBLE</codeph>, or
+ <codeph>DECIMAL(5,2)</codeph> or <codeph>DECIMAL(20,5)</codeph>.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>[localhost:21000] > create table h (x int, s string);
[localhost:21000] > insert into h values (0, 'hello'), (1,'world'), (1234567890,'antidisestablishmentarianism');
@@ -585,7 +848,8 @@ select fmod(9.9,3.3);
| antidisestablishmentarianism | 4 |
+------------------------------+-------------------------+</codeblock>
<p>
- For short argument values, the high-order bits of the result have relatively low entropy:
+ For short argument values, the high-order bits of the result have relatively low
+ entropy:
</p>
<codeblock>[localhost:21000] > create table b (x boolean);
[localhost:21000] > insert into b values (true), (true), (false), (false);
@@ -608,13 +872,12 @@ select fmod(9.9,3.3);
<dlentry rev="1.4.0" id="greatest">
<dt rev="1.4.0">
- <codeph>greatest(bigint a[, bigint b ...])</codeph>, <codeph>greatest(double a[, double b ...])</codeph>,
- <codeph>greatest(decimal(p,s) a[, decimal(p,s) b ...])</codeph>, <codeph>greatest(string a[, string b
- ...])</codeph>, <codeph>greatest(timestamp a[, timestamp b ...])</codeph>
+ GREATEST(BIGINT a[, BIGINT b ...]), GREATEST(DOUBLE a[, DOUBLE b ...]),
+ GREATEST(DECIMAL(p,s) a[, DECIMAL(p,s) b ...]), GREATEST(STRING a[, STRING b ...]),
+ GREATEST(TIMESTAMP a[, TIMESTAMP b ...])
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">greatest() function</indexterm>
<b>Purpose:</b> Returns the largest value from a list of expressions.
<p conref="../shared/impala_common.xml#common/return_same_type"/>
</dd>
@@ -624,15 +887,14 @@ select fmod(9.9,3.3);
<dlentry id="hex">
<dt>
- <codeph>hex(bigint a), hex(string a)</codeph>
+ HEX(BIGINT a), HEX(STRING a)
</dt>
<dd>
- <indexterm audience="hidden">hex() function</indexterm>
- <b>Purpose:</b> Returns the hexadecimal representation of an integer value, or of the characters in a
- string.
+ <b>Purpose:</b> Returns the hexadecimal representation of an integer value, or of the
+ characters in a string.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -641,16 +903,18 @@ select fmod(9.9,3.3);
<dlentry rev="1.4.0" id="is_inf">
<dt rev="1.4.0">
- <codeph>is_inf(double a)</codeph>,
+ IS_INF(DOUBLE a)
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">is_inf() function</indexterm>
- <b>Purpose:</b> Tests whether a value is equal to the special value <q>inf</q>, signifying infinity.
+ <b>Purpose:</b> Tests whether a value is equal to the special value <q>inf</q>,
+ signifying infinity.
<p>
- <b>Return type:</b> <codeph>boolean</codeph>
+ <b>Return type:</b> <codeph>BOOLEAN</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p conref="../shared/impala_common.xml#common/infinity_and_nan"/>
</dd>
@@ -659,17 +923,18 @@ select fmod(9.9,3.3);
<dlentry rev="1.4.0" id="is_nan">
<dt rev="1.4.0">
- <codeph>is_nan(double a)</codeph>,
+ IS_NAN(DOUBLE a)
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">is_nan() function</indexterm>
- <b>Purpose:</b> Tests whether a value is equal to the special value <q>NaN</q>, signifying <q>not a
- number</q>.
+ <b>Purpose:</b> Tests whether a value is equal to the special value <q>NaN</q>,
+ signifying <q>not a number</q>.
<p>
- <b>Return type:</b> <codeph>boolean</codeph>
+ <b>Return type:</b> <codeph>BOOLEAN</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p conref="../shared/impala_common.xml#common/infinity_and_nan"/>
</dd>
@@ -678,13 +943,12 @@ select fmod(9.9,3.3);
<dlentry rev="1.4.0" id="least">
<dt rev="1.4.0">
- <codeph>least(bigint a[, bigint b ...])</codeph>, <codeph>least(double a[, double b ...])</codeph>,
- <codeph>least(decimal(p,s) a[, decimal(p,s) b ...])</codeph>, <codeph>least(string a[, string b
- ...])</codeph>, <codeph>least(timestamp a[, timestamp b ...])</codeph>
+ LEAST(BIGINT a[, BIGINT b ...]), LEAST(DOUBLE a[, DOUBLE b ...]), LEAST(DECIMAL(p,s)
+ a[, DECIMAL(p,s) b ...]), LEAST(STRING a[, STRING b ...]), LEAST(TIMESTAMP a[,
+ TIMESTAMP b ...])
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">least() function</indexterm>
<b>Purpose:</b> Returns the smallest value from a list of expressions.
<p conref="../shared/impala_common.xml#common/return_same_type"/>
</dd>
@@ -694,18 +958,17 @@ select fmod(9.9,3.3);
<dlentry id="ln">
<dt>
- <codeph>ln(double a)</codeph>,
- <codeph rev="2.3.0" id="dlog1">dlog1(double a)</codeph>
+ LN(DOUBLE a), DLOG1(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">ln() function</indexterm>
- <indexterm audience="hidden">dlog1() function</indexterm>
<b>Purpose:</b> Returns the
- <xref href="https://en.wikipedia.org/wiki/Natural_logarithm" scope="external" format="html">natural
+ <xref
+ href="https://en.wikipedia.org/wiki/Natural_logarithm"
+ scope="external" format="html">natural
logarithm</xref> of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -714,14 +977,13 @@ select fmod(9.9,3.3);
<dlentry id="log">
<dt>
- <codeph>log(double base, double a)</codeph>
+ LOG(DOUBLE base, DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">log() function</indexterm>
<b>Purpose:</b> Returns the logarithm of the second argument to the specified base.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -730,16 +992,13 @@ select fmod(9.9,3.3);
<dlentry id="log10">
<dt>
- <codeph>log10(double a)</codeph>,
- <codeph rev="2.3.0" id="dlog10">dlog10(double a)</codeph>
+ LOG10(DOUBLE a), DLOG10(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">log10() function</indexterm>
- <indexterm audience="hidden">dlog10() function</indexterm>
<b>Purpose:</b> Returns the logarithm of the argument to the base 10.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -748,14 +1007,13 @@ select fmod(9.9,3.3);
<dlentry id="log2">
<dt>
- <codeph>log2(double a)</codeph>
+ LOG2(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">log2() function</indexterm>
<b>Purpose:</b> Returns the logarithm of the argument to the base 2.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -764,25 +1022,21 @@ select fmod(9.9,3.3);
<dlentry rev="1.4.0" id="max_int">
<dt rev="1.4.0">
- <codeph>max_int(), <ph id="max_tinyint">max_tinyint()</ph>, <ph id="max_smallint">max_smallint()</ph>,
- <ph id="max_bigint">max_bigint()</ph></codeph>
+ MAX_INT(), MAX_TINYINT(), MAX_SMALLINT(), MAX_BIGINT()
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">max_int() function</indexterm>
- <indexterm audience="hidden">max_tinyint() function</indexterm>
- <indexterm audience="hidden">max_smallint() function</indexterm>
- <indexterm audience="hidden">max_bigint() function</indexterm>
<b>Purpose:</b> Returns the largest value of the associated integral type.
<p>
<b>Return type:</b> The same as the integral type being checked.
</p>
+
<p>
-<!-- Repeated usage text between max_ and min_ functions, could turn into a conref. -->
- <b>Usage notes:</b> Use the corresponding <codeph>min_</codeph> and <codeph>max_</codeph> functions to
- check if all values in a column are within the allowed range, before copying data or altering column
- definitions. If not, switch to the next higher integral type or to a <codeph>DECIMAL</codeph> with
- sufficient precision.
+ <b>Usage notes:</b> Use the corresponding <codeph>min_</codeph> and
+ <codeph>max_</codeph> functions to check if all values in a column are within the
+ allowed range, before copying data or altering column definitions. If not, switch to
+ the next higher integral type or to a <codeph>DECIMAL</codeph> with sufficient
+ precision.
</p>
</dd>
@@ -791,24 +1045,22 @@ select fmod(9.9,3.3);
<dlentry rev="1.4.0" id="min_int">
<dt rev="1.4.0">
- <codeph>min_int(), <ph id="min_tinyint">min_tinyint()</ph>, <ph id="min_smallint">min_smallint()</ph>,
- <ph id="min_bigint">min_bigint()</ph></codeph>
+ MIN_INT(), MIN_TINYINT(), MIN_SMALLINT(), MIN_BIGINT()
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">min_int() function</indexterm>
- <indexterm audience="hidden">min_tinyint() function</indexterm>
- <indexterm audience="hidden">min_smallint() function</indexterm>
- <indexterm audience="hidden">min_bigint() function</indexterm>
- <b>Purpose:</b> Returns the smallest value of the associated integral type (a negative number).
+ <b>Purpose:</b> Returns the smallest value of the associated integral type (a negative
+ number).
<p>
<b>Return type:</b> The same as the integral type being checked.
</p>
+
<p>
- <b>Usage notes:</b> Use the corresponding <codeph>min_</codeph> and <codeph>max_</codeph> functions to
- check if all values in a column are within the allowed range, before copying data or altering column
- definitions. If not, switch to the next higher integral type or to a <codeph>DECIMAL</codeph> with
- sufficient precision.
+ <b>Usage notes:</b> Use the corresponding <codeph>min_</codeph> and
+ <codeph>max_</codeph> functions to check if all values in a column are within the
+ allowed range, before copying data or altering column definitions. If not, switch to
+ the next higher integral type or to a <codeph>DECIMAL</codeph> with sufficient
+ precision.
</p>
</dd>
@@ -817,35 +1069,44 @@ select fmod(9.9,3.3);
<dlentry id="mod" rev="2.2.0">
<dt rev="2.2.0">
- <codeph>mod(<varname>numeric_type</varname> a, <varname>same_type</varname> b)</codeph>
+ MOD(numeric_type a, same_type b)
</dt>
<dd rev="2.2.0">
- <indexterm audience="hidden">mod() function</indexterm>
- <b>Purpose:</b> Returns the modulus of a number. Equivalent to the
- <codeph>%</codeph> arithmetic operator. Works with any size integer
- type, any size floating-point type, and <codeph>DECIMAL</codeph> with
- any precision and scale. <p
+ <b>Purpose:</b> Returns the modulus of a number. Equivalent to the <codeph>%</codeph>
+ arithmetic operator. Works with any size integer type, any size floating-point type,
+ and <codeph>DECIMAL</codeph> with any precision and scale.
+ <p
conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_220"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p> Because this function works with <codeph>DECIMAL</codeph> values,
- prefer it over <codeph>fmod()</codeph> when working with fractional
- values. It is not subject to the rounding errors that make
- <codeph>fmod()</codeph> problematic with floating-point
- numbers.</p><p rev="IMPALA-6202">Query plans shows the
- <codeph>MOD()</codeph> function as the <codeph>%</codeph>
- operator.</p>
+
+ <p>
+ Because this function works with <codeph>DECIMAL</codeph> values, prefer it over
+ <codeph>fmod()</codeph> when working with fractional values. It is not subject to
+ the rounding errors that make <codeph>fmod()</codeph> problematic with
+ floating-point numbers.
+ </p>
+
+ <p rev="IMPALA-6202">
+ Query plans shows the <codeph>MOD()</codeph> function as the <codeph>%</codeph>
+ operator.
+ </p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
- <p> The following examples show how the <codeph>mod()</codeph>
- function works for whole numbers and fractional values, and how the
- <codeph>%</codeph> operator works the same way. In the case of
- <codeph>mod(9.9,3)</codeph>, the type conversion for the second
- argument results in the first argument being interpreted as
- <codeph>DOUBLE</codeph>, so to produce an accurate
- <codeph>DECIMAL</codeph> result requires casting the second
- argument or writing it as a <codeph>DECIMAL</codeph> literal, 3.0. </p>
- <codeblock>select mod(10,3);
+
+ <p>
+ The following examples show how the <codeph>mod()</codeph> function works for whole
+ numbers and fractional values, and how the <codeph>%</codeph> operator works the
+ same way. In the case of <codeph>mod(9.9,3)</codeph>, the type conversion for the
+ second argument results in the first argument being interpreted as
+ <codeph>DOUBLE</codeph>, so to produce an accurate <codeph>DECIMAL</codeph> result
+ requires casting the second argument or writing it as a <codeph>DECIMAL</codeph>
+ literal, 3.0.
+ </p>
+<codeblock>select mod(10,3);
+-------------+
| fmod(10, 3) |
+-------------+
@@ -908,34 +1169,46 @@ select mod(9.9,3.0);
<dlentry id="murmur_hash" rev="IMPALA-3651 2.12.0">
<dt rev="2.12.0">
- <codeph>murmur_hash(type v)</codeph>
+ MURMUR_HASH(type v)
</dt>
<dd rev="2.12.0">
- <indexterm audience="hidden">murmur_hash() function</indexterm>
- <b>Purpose:</b> Returns a consistent 64-bit value derived from the input argument, for convenience of
- implementing <xref keyref="MurmurHash"> MurmurHash2</xref> non-cryptographic hash function.
+ <b>Purpose:</b> Returns a consistent 64-bit value derived from the input argument, for
+ convenience of implementing <xref
+ keyref="MurmurHash"> MurmurHash2</xref>
+ non-cryptographic hash function.
<p>
<b>Return type:</b> <codeph>BIGINT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- You might use the return value in an application where you perform load balancing, bucketing, or some
- other technique to divide processing or storage. This function provides a good performance for all kinds
- of keys such as number, ascii string and UTF-8. It can be recommended as general-purpose hashing function.
+ You might use the return value in an application where you perform load balancing,
+ bucketing, or some other technique to divide processing or storage. This function
+ provides a good performance for all kinds of keys such as number, ascii string and
+ UTF-8. It can be recommended as general-purpose hashing function.
</p>
+
<p>
- Regarding comparison of murmur_hash with fnv_hash, murmur_hash is based on Murmur2 hash algorithm and fnv_hash
- function is based on FNV-1a hash algorithm. Murmur2 and FNV-1a can show very good randomness and performance
- compared with well known other hash algorithms, but Murmur2 slightly show better randomness and performance than FNV-1a.
- See <xref keyref="hash_functions1">[1]</xref><xref keyref="hash_functions2">[2]</xref><xref keyref="hash_functions1">[3]</xref> for details.
+ Regarding comparison of murmur_hash with fnv_hash, murmur_hash is based on Murmur2
+ hash algorithm and fnv_hash function is based on FNV-1a hash algorithm. Murmur2 and
+ FNV-1a can show very good randomness and performance compared with well known other
+ hash algorithms, but Murmur2 slightly show better randomness and performance than
+ FNV-1a. See
+ <xref keyref="hash_functions1"
+ >[1]</xref><xref keyref="hash_functions2">[2]</xref><xref
+ keyref="hash_functions1">[3]</xref>
+ for details.
</p>
+
<p>
- Similar input values of different types could produce different hash values, for example the same
- numeric value represented as <codeph>SMALLINT</codeph> or <codeph>BIGINT</codeph>,
- <codeph>FLOAT</codeph> or <codeph>DOUBLE</codeph>, or <codeph>DECIMAL(5,2)</codeph> or
- <codeph>DECIMAL(20,5)</codeph>.
+ Similar input values of different types could produce different hash values, for
+ example the same numeric value represented as <codeph>SMALLINT</codeph> or
+ <codeph>BIGINT</codeph>, <codeph>FLOAT</codeph> or <codeph>DOUBLE</codeph>, or
+ <codeph>DECIMAL(5,2)</codeph> or <codeph>DECIMAL(20,5)</codeph>.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>[localhost:21000] > create table h (x int, s string);
[localhost:21000] > insert into h values (0, 'hello'), (1,'world'), (1234567890,'antidisestablishmentarianism');
@@ -956,7 +1229,8 @@ select mod(9.9,3.0);
| antidisestablishmentarianism | -2261804666958489663 |
+------------------------------+----------------------+ </codeblock>
<p>
- For short argument values, the high-order bits of the result have relatively higher entropy than fnv_hash:
+ For short argument values, the high-order bits of the result have relatively higher
+ entropy than fnv_hash:
</p>
<codeblock>[localhost:21000] > create table b (x boolean);
[localhost:21000] > insert into b values (true), (true), (false), (false);
@@ -979,24 +1253,18 @@ select mod(9.9,3.0);
<dlentry rev="1.4.0" id="negative">
<dt rev="2.0.1">
- <codeph>negative(numeric_type a)</codeph>
-<!-- <codeph>negative(int a), negative(double a), negative(decimal(p,s) a)</codeph> -->
+ NEGATIVE(numeric_type a)
</dt>
<dd>
- <indexterm audience="hidden">negative() function</indexterm>
- <b>Purpose:</b> Returns the argument with the sign reversed; returns a positive value if the argument was
- already negative.
- <p rev="2.0.1" conref="../shared/impala_common.xml#common/return_type_same"/>
-<!--
- <p>
- <b>Return type:</b> <codeph>int</codeph>, <codeph>double</codeph>,
- or <codeph>decimal(p,s)</codeph> depending on type of argument
- </p>
- -->
+ <b>Purpose:</b> Returns the argument with the sign reversed; returns a positive value
+ if the argument was already negative.
+ <p rev="2.0.1"
+ conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p>
- <b>Usage notes:</b> Use <codeph>-abs(a)</codeph> instead if you need to ensure all return values are
- negative.
+ <b>Usage notes:</b> Use <codeph>-ABS(a)</codeph> instead if you need to ensure all
+ return values are negative.
</p>
</dd>
@@ -1005,14 +1273,13 @@ select mod(9.9,3.0);
<dlentry id="pi">
<dt rev="1.4.0">
- <codeph>pi()</codeph>
+ PI()
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">pi() function</indexterm>
<b>Purpose:</b> Returns the constant pi.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1021,21 +1288,26 @@ select mod(9.9,3.0);
<dlentry id="pmod">
<dt>
- <codeph>pmod(bigint a, bigint b), pmod(double a, double b)</codeph>
+ PMOD(BIGINT a, BIGINT b), PMOD(DOUBLE a, DOUBLE b)
</dt>
<dd>
- <indexterm audience="hidden">pmod() function</indexterm>
- <b>Purpose:</b> Returns the positive modulus of a number.
- Primarily for <xref href="https://issues.apache.org/jira/browse/HIVE-656" scope="external" format="html">HiveQL compatibility</xref>.
+ <b>Purpose:</b> Returns the positive modulus of a number. Primarily for
+ <xref href="https://issues.apache.org/jira/browse/HIVE-656"
+ scope="external" format="html">HiveQL
+ compatibility</xref>.
<p>
- <b>Return type:</b> <codeph>int</codeph> or <codeph>double</codeph>, depending on type of arguments
+ <b>Return type:</b> <codeph>INT</codeph> or <codeph>DOUBLE</codeph>, depending on
+ type of arguments
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show how the <codeph>fmod()</codeph> function sometimes returns a negative value
- depending on the sign of its arguments, and the <codeph>pmod()</codeph> function returns the same value
- as <codeph>fmod()</codeph>, but sometimes with the sign flipped.
+ The following examples show how the <codeph>FMOD()</codeph> function sometimes
+ returns a negative value depending on the sign of its arguments, and the
+ <codeph>PMOD()</codeph> function returns the same value as <codeph>FMOD()</codeph>,
+ but sometimes with the sign flipped.
</p>
<codeblock>select fmod(-5,2);
+-------------+
@@ -1086,23 +1358,18 @@ select pmod(5,-2);
<dlentry rev="1.4.0" id="positive">
<dt rev="2.0.1">
- <codeph>positive(numeric_type a)</codeph>
-<!-- <codeph>positive(int a), positive(double a), positive(decimal(p,s) a</codeph> -->
+ POSITIVE(numeric_type a)
</dt>
<dd>
- <indexterm audience="hidden">positive() function</indexterm>
- <b>Purpose:</b> Returns the original argument unchanged (even if the argument is negative).
- <p rev="2.0.1" conref="../shared/impala_common.xml#common/return_type_same"/>
-<!--
- <p>
- <b>Return type:</b> <codeph>int</codeph>, <codeph>double</codeph>,
- or <codeph>decimal(p,s)</codeph> depending on type of argument
- </p>
- -->
+ <b>Purpose:</b> Returns the original argument unchanged (even if the argument is
+ negative).
+ <p rev="2.0.1"
+ conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p>
- <b>Usage notes:</b> Use <codeph>abs()</codeph> instead if you need to ensure all return values are
- positive.
+ <b>Usage notes:</b> Use <codeph>ABS()</codeph> instead if you need to ensure all
+ return values are positive.
</p>
</dd>
@@ -1111,20 +1378,14 @@ select pmod(5,-2);
<dlentry id="pow">
<dt rev="1.4.0">
- <codeph>pow(double a, double p)</codeph>,
- <codeph id="power">power(double a, double p)</codeph>,
- <codeph rev="2.3.0" id="dpow">dpow(double a, double p)</codeph>,
- <codeph rev="2.3.0" id="fpow">fpow(double a, double p)</codeph>
+ POW(DOUBLE a, DOUBLE p), POWER(DOUBLE a, DOUBLE p), DPOW(DOUBLE a, DOUBLE p),
+ FPOW(DOUBLE a, DOUBLE p)
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">pow() function</indexterm>
- <indexterm audience="hidden">power() function</indexterm>
- <indexterm audience="hidden">dpow() function</indexterm>
- <indexterm audience="hidden">fpow() function</indexterm>
<b>Purpose:</b> Returns the first argument raised to the power of the second argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1133,24 +1394,31 @@ select pmod(5,-2);
<dlentry rev="1.4.0" id="precision">
<dt rev="1.4.0">
- <codeph>precision(<varname>numeric_expression</varname>)</codeph>
+ PRECISION(numeric_expression)
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">precision() function</indexterm>
- <b>Purpose:</b> Computes the precision (number of decimal digits) needed to represent the type of the
- argument expression as a <codeph>DECIMAL</codeph> value.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> Computes the precision (number of decimal digits) needed to represent
+ the type of the argument expression as a <codeph>DECIMAL</codeph> value.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Typically used in combination with the <codeph>scale()</codeph> function, to determine the appropriate
- <codeph>DECIMAL(<varname>precision</varname>,<varname>scale</varname>)</codeph> type to declare in a
- <codeph>CREATE TABLE</codeph> statement or <codeph>CAST()</codeph> function.
+ Typically used in combination with the <codeph>SCALE()</codeph> function, to
+ determine the appropriate
+ <codeph>DECIMAL(<varname>precision</varname>,<varname>scale</varname>)</codeph> type
+ to declare in a <codeph>CREATE TABLE</codeph> statement or <codeph>CAST()</codeph>
+ function.
</p>
+
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
- <p conref="../shared/impala_common.xml#common/precision_scale_example"/>
+
+ <p conref="../shared/impala_common.xml#common/precision_scale_example"
+ />
</dd>
</dlentry>
@@ -1158,19 +1426,20 @@ select pmod(5,-2);
<dlentry id="quotient">
<dt>
- <codeph>quotient(bigint numerator, bigint denominator)</codeph>,
- <codeph>quotient(double numerator, double denominator)</codeph>
+ QUOTIENT(BIGINT numerator, BIGINT denominator), QUOTIENT(DOUBLE numerator, DOUBLE
+ denominator)
</dt>
<dd>
- <indexterm audience="hidden">quotient() function</indexterm>
- <b>Purpose:</b> Returns the first argument divided by the second argument, discarding any fractional
- part. Avoids promoting integer arguments to <codeph>DOUBLE</codeph> as happens with the <codeph>/</codeph> SQL
- operator. <ph rev="IMPALA-278">Also includes an overload that accepts <codeph>DOUBLE</codeph> arguments,
- discards the fractional part of each argument value before dividing, and again returns <codeph>BIGINT</codeph>.
- With integer arguments, this function works the same as the <codeph>DIV</codeph> operator.</ph>
+ <b>Purpose:</b> Returns the first argument divided by the second argument, discarding
+ any fractional part. Avoids promoting integer arguments to <codeph>DOUBLE</codeph> as
+ happens with the <codeph>/</codeph> SQL operator. <ph rev="IMPALA-278">Also includes
+ an overload that accepts <codeph>DOUBLE</codeph> arguments, discards the fractional
+ part of each argument value before dividing, and again returns
+ <codeph>BIGINT</codeph>. With integer arguments, this function works the same as the
+ <codeph>DIV</codeph> operator.</ph>
<p>
- <b>Return type:</b> <codeph>bigint</codeph>
+ <b>Return type:</b> <codeph>BIGINT</codeph>
</p>
</dd>
@@ -1179,14 +1448,13 @@ select pmod(5,-2);
<dlentry id="radians">
<dt>
- <codeph>radians(double a)</codeph>
+ RADIANS(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">radians() function</indexterm>
<b>Purpose:</b> Converts argument value from degrees to radians.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1195,37 +1463,41 @@ select pmod(5,-2);
<dlentry id="rand">
<dt>
- <codeph>rand()</codeph>, <codeph>rand(bigint seed)</codeph>,
- <codeph rev="2.3.0" id="random">random()</codeph>,
- <codeph rev="2.3.0">random(bigint seed)</codeph>
+ RAND(), RAND(BIGINT seed), RANDOME(), RANDOME(BIGINT seed)
</dt>
<dd>
- <indexterm audience="hidden">rand() function</indexterm>
- <b>Purpose:</b> Returns a random value between 0 and 1. After <codeph>rand()</codeph> is called with a
- seed argument, it produces a consistent random sequence based on the seed value.
+ <b>Purpose:</b> Returns a random value between 0 and 1. After <codeph>RAND()</codeph>
+ is called with a seed argument, it produces a consistent random sequence based on the
+ seed value.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
+
<p>
- <b>Usage notes:</b> Currently, the random sequence is reset after each query, and multiple calls to
- <codeph>rand()</codeph> within the same query return the same value each time. For different number
- sequences that are different for each query, pass a unique seed value to each call to
- <codeph>rand()</codeph>. For example, <codeph>select rand(unix_timestamp()) from ...</codeph>
+ <b>Usage notes:</b> Currently, the random sequence is reset after each query, and
+ multiple calls to <codeph>RAND()</codeph> within the same query return the same
+ value each time. For different number sequences that are different for each query,
+ pass a unique seed value to each call to <codeph>RAND()</codeph>. For example,
+ <codeph>SELECT RAND(UNIX_TIMESTAMP()) FROM ...</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show how <codeph>rand()</codeph> can produce sequences of varying predictability,
- so that you can reproduce query results involving random values or generate unique sequences of random
- values for each query.
- When <codeph>rand()</codeph> is called with no argument, it generates the same sequence of values each time,
- regardless of the ordering of the result set.
- When <codeph>rand()</codeph> is called with a constant integer, it generates a different sequence of values,
- but still always the same sequence for the same seed value.
- If you pass in a seed value that changes, such as the return value of the expression <codeph>unix_timestamp(now())</codeph>,
- each query will use a different sequence of random values, potentially more useful in probability calculations although
- more difficult to reproduce at a later time. Therefore, the final two examples with an unpredictable seed value
- also include the seed in the result set, to make it possible to reproduce the same random sequence later.
+ The following examples show how <codeph>rand()</codeph> can produce sequences of
+ varying predictability, so that you can reproduce query results involving random
+ values or generate unique sequences of random values for each query. When
+ <codeph>rand()</codeph> is called with no argument, it generates the same sequence
+ of values each time, regardless of the ordering of the result set. When
+ <codeph>rand()</codeph> is called with a constant integer, it generates a different
+ sequence of values, but still always the same sequence for the same seed value. If
+ you pass in a seed value that changes, such as the return value of the expression
+ <codeph>unix_timestamp(now())</codeph>, each query will use a different sequence of
+ random values, potentially more useful in probability calculations although more
+ difficult to reproduce at a later time. Therefore, the final two examples with an
+ unpredictable seed value also include the seed in the result set, to make it
+ possible to reproduce the same random sequence later.
</p>
<codeblock>select x, rand() from three_rows;
+---+-----------------------+
@@ -1290,24 +1562,17 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry id="round">
<dt>
- <codeph>round(double a)</codeph>,
- <codeph>round(double a, int d)</codeph>,
- <codeph rev="1.4.0">round(decimal a, int_type d)</codeph>,
- <codeph rev="2.3.0" id="dround">dround(double a)</codeph>,
- <codeph rev="2.3.0">dround(double a, int d)</codeph>,
- <codeph rev="2.3.0">dround(decimal(p,s) a, int_type d)</codeph>
+ ROUND(DOUBLE a), ROUND(DOUBLE a, INT d), ROUND(DECIMAL a, int_type d), DROUND(DOUBLE
+ a), DROUND(DOUBLE a, INT d), DROUND(DECIMAL(p,s) a, int_type d)
</dt>
<dd>
- <indexterm audience="hidden">round() function</indexterm>
- <indexterm audience="hidden">dround() function</indexterm>
- <b>Purpose:</b> Rounds a floating-point value. By default (with a
- single argument), rounds to the nearest integer. Values ending in .5
- are rounded up for positive numbers, down for negative numbers (that
- is, away from zero). The optional second argument specifies how many
- digits to leave after the decimal point; values greater than zero
- produce a floating-point return value rounded to the requested number
- of digits to the right of the decimal point.
+ <b>Purpose:</b> Rounds a floating-point value. By default (with a single argument),
+ rounds to the nearest integer. Values ending in .5 are rounded up for positive
+ numbers, down for negative numbers (that is, away from zero). The optional second
+ argument specifies how many digits to leave after the decimal point; values greater
+ than zero produce a floating-point return value rounded to the requested number of
+ digits to the right of the decimal point.
<p rev="1.4.0">
<b>Return type:</b> Same as the input type
</p>
@@ -1318,24 +1583,32 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry rev="1.4.0" id="scale">
<dt rev="1.4.0">
- <codeph>scale(<varname>numeric_expression</varname>)</codeph>
+ SCALE(numeric_expression)
</dt>
<dd rev="1.4.0">
- <indexterm audience="hidden">scale() function</indexterm>
- <b>Purpose:</b> Computes the scale (number of decimal digits to the right of the decimal point) needed to
- represent the type of the argument expression as a <codeph>DECIMAL</codeph> value.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> Computes the scale (number of decimal digits to the right of the
+ decimal point) needed to represent the type of the argument expression as a
+ <codeph>DECIMAL</codeph> value.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Typically used in combination with the <codeph>precision()</codeph> function, to determine the
- appropriate <codeph>DECIMAL(<varname>precision</varname>,<varname>scale</varname>)</codeph> type to
- declare in a <codeph>CREATE TABLE</codeph> statement or <codeph>CAST()</codeph> function.
+ Typically used in combination with the <codeph>PRECISION()</codeph> function, to
+ determine the appropriate
+ <codeph>DECIMAL(<varname>precision</varname>,<varname>scale</varname>)</codeph> type
+ to declare in a <codeph>CREATE TABLE</codeph> statement or <codeph>CAST()</codeph>
+ function.
</p>
+
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
- <p conref="../shared/impala_common.xml#common/precision_scale_example"/>
+
+ <p conref="../shared/impala_common.xml#common/precision_scale_example"
+ />
</dd>
</dlentry>
@@ -1343,14 +1616,13 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry id="sign">
<dt>
- <codeph>sign(double a)</codeph>
+ SIGN(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">sign() function</indexterm>
<b>Purpose:</b> Returns -1, 0, or 1 to indicate the signedness of the argument value.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
</dd>
@@ -1359,14 +1631,13 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry id="sin">
<dt>
- <codeph>sin(double a)</codeph>
+ SIN(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">sin() function</indexterm>
<b>Purpose:</b> Returns the sine of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1375,14 +1646,13 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry id="sinh" rev="2.3.0 IMPALA-1771">
<dt rev="2.3.0 IMPALA-1771">
- <codeph>sinh(double a)</codeph>
+ SINH(DOUBLE a)
</dt>
<dd rev="2.3.0 IMPALA-1771">
- <indexterm audience="hidden">sinh() function</indexterm>
<b>Purpose:</b> Returns the hyperbolic sine of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1391,16 +1661,13 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry id="sqrt">
<dt>
- <codeph>sqrt(double a)</codeph>,
- <codeph rev="2.3.0" id="dsqrt">dsqrt(double a)</codeph>
+ SQRT(DOUBLE a), DSQRT(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">sqrt() function</indexterm>
- <indexterm audience="hidden">dsqrt() function</indexterm>
<b>Purpose:</b> Returns the square root of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1409,14 +1676,13 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry id="tan">
<dt>
- <codeph>tan(double a)</codeph>
+ TAN(DOUBLE a)
</dt>
<dd>
- <indexterm audience="hidden">tan() function</indexterm>
<b>Purpose:</b> Returns the tangent of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1425,14 +1691,13 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry id="tanh" rev="2.3.0 IMPALA-1771">
<dt rev="2.3.0 IMPALA-1771">
- <codeph>tanh(double a)</codeph>
+ TANH(DOUBLE a)
</dt>
<dd rev="2.3.0 IMPALA-1771">
- <indexterm audience="hidden">tanh() function</indexterm>
<b>Purpose:</b> Returns the hyperbolic tangent of the argument.
<p>
- <b>Return type:</b> <codeph>double</codeph>
+ <b>Return type:</b> <codeph>DOUBLE</codeph>
</p>
</dd>
@@ -1441,62 +1706,67 @@ select x, unix_timestamp(now()), rand(unix_timestamp(now()))
<dlentry rev="2.3.0" id="truncate">
<dt rev="2.3.0">
- <codeph>truncate(double_or_decimal a[, digits_to_leave])</codeph>,
- <ph id="dtrunc"><codeph>dtrunc(double_or_decimal a[, digits_to_leave])</codeph></ph>,
- <ph rev="2.10.0 IMPALA-5529" id="trunc_number"><codeph>trunc(double_or_decimal a[, digits_to_leave])</codeph></ph>
+ TRUNCATE(DOUBLE_or_DECIMAL a[, digits_to_leave]), DTRUNC(DOUBLE_or_DECIMAL a[,
+ digits_to_leave]), TRUNC(DOUBLE_or_DECIMAL a[, digits_to_leave])
</dt>
<dd rev="2.3.0">
- <indexterm audience="hidden">truncate() function</indexterm>
- <indexterm audience="hidden">dtrunc() function</indexterm>
- <indexterm audience="hidden">trunc() function</indexterm>
<b>Purpose:</b> Removes some or all fractional digits from a numeric value.
<p>
- <b>Arguments:</b>
- With a single floating-point argument, removes all fractional digits, leaving an
- integer value. The optional second argument specifies the number of fractional digits
- to include in the return value, and only applies when the argument type is
- <codeph>DECIMAL</codeph>. A second argument of 0 truncates to a whole integer value.
- A second argument of negative N sets N digits to 0 on the left side of the decimal
+ <b>Arguments:</b> With a single floating-point argument, removes all fractional
+ digits, leaving an integer value. The optional second argument specifies the number
+ of fractional digits to include in the return value, and only applies when the
+ argument type is <codeph>DECIMAL</codeph>. A second argument of 0 truncates to a
+ whole integer value. A second argument of negative N sets N digits to 0 on the left
+ side of the decimal
</p>
+
<p rev="2.10.0 IMPALA-5529">
<b>Scale argument:</b> The scale argument applies only when truncating
- <codeph>DECIMAL</codeph> values. It is an integer specifying how many
- significant digits to leave to the right of the decimal point.
- A scale argument of 0 truncates to a whole integer value. A scale
- argument of negative N sets N digits to 0 on the left side of the decimal
- point.
+ <codeph>DECIMAL</codeph> values. It is an integer specifying how many significant
+ digits to leave to the right of the decimal point. A scale argument of 0 truncates
+ to a whole integer value. A scale argument of negative N sets N digits to 0 on the
+ left side of the decimal point.
</p>
+
<p>
- <codeph>truncate()</codeph>, <codeph>dtrunc()</codeph>,
- <ph rev="2.10.0 IMPALA-5529">and <codeph>trunc()</codeph></ph> are aliases for the
- same function.
+ <codeph>TRUNCATE()</codeph>, <codeph>DTRUNC()</codeph>,
+ <ph
+ rev="2.10.0 IMPALA-5529">and <codeph>TRUNC()</codeph></ph> are
+ aliases for the same function.
</p>
+
<p>
<b>Return type:</b> Same as the input type
</p>
+
<p>
- <b>Added in:</b> The <codeph>trunc()</codeph> alias was added in
+ <b>Added in:</b> The <codeph>TRUNC()</codeph> alias was added in
<keyword keyref="impala210_full"/>.
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p rev="2.10.0 IMPALA-5529">
You can also pass a <codeph>DOUBLE</codeph> argument, or <codeph>DECIMAL</codeph>
- argument with optional scale, to the <codeph>dtrunc()</codeph> or
- <codeph>truncate</codeph> functions. Using the <codeph>trunc()</codeph>
- function for numeric values is common with other industry-standard database
- systems, so you might find such <codeph>trunc()</codeph> calls in code that you
- are porting to Impala.
+ argument with optional scale, to the <codeph>DTRUNC()</codeph> or
+ <codeph>TRUNCATE</codeph> functions. Using the <codeph>TRUNC()</codeph> function for
+ numeric values is common with other industry-standard database systems, so you might
+ find such <codeph>TRUNC()</codeph> calls in code that you are porting to Impala.
</p>
+
<p>
- The <codeph>trunc()</codeph> function also has a signature that applies to
- <codeph>TIMESTAMP</codeph> values. See <xref keyref="datetime_functions"/>
- for details.
+ The <codeph>TRUNC()</codeph> function also has a signature that applies to
+ <codeph>TIMESTAMP</codeph> values. See
+ <xref
+ keyref="datetime_functions"/> for details.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples demonstrate the <codeph>truncate()</codeph>
- and <codeph>dtrunc()</codeph> signatures for this function:
+ The following examples demonstrate the <codeph>TRUNCATE()</codeph> and
+ <codeph>DTRUNC()</codeph> signatures for this function:
</p>
<codeblock>select truncate(3.45);
+----------------+
@@ -1542,10 +1812,9 @@ select truncate(3.456,7);
</codeblock>
<p rev="2.10.0 IMPALA-5529">
The following examples demonstrate using <codeph>trunc()</codeph> with
- <codeph>DECIMAL</codeph> or <codeph>DOUBLE</codeph> values, and with
- an optional scale argument for <codeph>DECIMAL</codeph> values.
- (The behavior is the same for the <codeph>truncate()</codeph> and
- <codeph>dtrunc()</codeph> aliases also.)
+ <codeph>DECIMAL</codeph> or <codeph>DOUBLE</codeph> values, and with an optional
+ scale argument for <codeph>DECIMAL</codeph> values. (The behavior is the same for
+ the <codeph>truncate()</codeph> and <codeph>dtrunc()</codeph> aliases also.)
</p>
<codeblock rev="2.10.0 IMPALA-5529">
create table t1 (d decimal(20,7));
@@ -1618,7 +1887,6 @@ from t1 order by d;
| 9999.99 | 15 | 2 |
+-------------+----+---+
</codeblock>
-
<codeblock rev="2.10.0 IMPALA-5529">
create table dbl (d double);
@@ -1647,92 +1915,121 @@ select trunc(d) from dbl order by d;
<dlentry id="unhex">
<dt>
- <codeph>unhex(string a)</codeph>
+ UNHEX(STRING a)
</dt>
<dd>
- <indexterm audience="hidden">unhex() function</indexterm>
- <b>Purpose:</b> Returns a string of characters with ASCII values corresponding to pairs of hexadecimal
- digits in the argument.
+ <b>Purpose:</b> Returns a string of characters with ASCII values corresponding to
+ pairs of hexadecimal digits in the argument.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
</dlentry>
- <dlentry>
+
+ <dlentry id="width_bucket">
+
<dt>
- <codeph>width_bucket(decimal expr, decimal min_value, decimal
- max_value, int num_buckets)</codeph>
+ WIDTH_BUCKET(DECIMAL expr, DECIMAL min_value, DECIMAL max_value, INT num_buckets)
</dt>
+
<dd>
- <b>Purpose:</b> Returns the bucket number in which the
- <codeph>expr</codeph> value would fall in the histogram where its
- range between <codeph>min_value</codeph> and
- <codeph>max_value</codeph> is divided into
- <codeph>num_buckets</codeph> buckets of identical sizes. </dd>
- <dd>The function returns: <ul>
- <li><codeph>NULL</codeph> if any argument is
- <codeph>NULL</codeph>.</li>
- <li><codeph>0</codeph> if <codeph>expr</codeph> <
- <codeph>min_value</codeph>.</li>
- <li><codeph>num_buckets + 1</codeph> if <codeph>expr</codeph> >=
- <codeph>max_val</codeph>.</li>
- <li>If none of the above, the bucket number where
- <codeph>expr</codeph> falls.</li>
+ <b>Purpose:</b> Returns the bucket number in which the <codeph>expr</codeph> value
+ would fall in the histogram where its range between <codeph>min_value</codeph> and
+ <codeph>max_value</codeph> is divided into <codeph>num_buckets</codeph> buckets of
+ identical sizes.
+ </dd>
+
+ <dd>
+ The function returns:
+ <ul>
+ <li>
+ <codeph>NULL</codeph> if any argument is <codeph>NULL</codeph>.
+ </li>
+
+ <li>
+ <codeph>0</codeph> if <codeph>expr</codeph> < <codeph>min_value</codeph>.
+ </li>
+
+ <li>
+ <codeph>num_buckets + 1</codeph> if <codeph>expr</codeph> >=
+ <codeph>max_val</codeph>.
+ </li>
+
+ <li>
+ If none of the above, the bucket number where <codeph>expr</codeph> falls.
+ </li>
</ul>
<p>
- <b>Arguments:</b>The following rules apply to the arguments. <ul>
+ <b>Arguments:</b>The following rules apply to the arguments.
+ <ul>
<li>
- <codeph>min_val</codeph> is the minimum value of the histogram
- range. </li>
+ <codeph>min_val</codeph> is the minimum value of the histogram range.
+ </li>
+
<li>
- <codeph>max_val</codeph> is the maximum value of the histogram
- range. </li>
+ <codeph>max_val</codeph> is the maximum value of the histogram range.
+ </li>
+
<li>
- <codeph>num_buckets</codeph> must be greater than
- <codeph>0</codeph>. </li>
+ <codeph>num_buckets</codeph> must be greater than <codeph>0</codeph>.
+ </li>
+
<li>
- <codeph>min_value</codeph> must be less than
- <codeph>max_value</codeph>. </li>
+ <codeph>min_value</codeph> must be less than <codeph>max_value</codeph>.
+ </li>
</ul>
</p>
+
<p>
- <b>Usage notes:</b></p><p>Each bucket contains values equal to or
- greater than the base value of that bucket and less than the base
- value of the next bucket. For example, with <codeph>width_bucket(8,
- 1, 10, 3)</codeph>, the bucket ranges are actually the 0th
- "underflow bucket" with the range (-infinity to 0.999...), (1 to
- 3.999...), (4, to 6.999...), (7 to 9.999...), and the "overflow
- bucket" with the range (10 to infinity).</p>
+ <b>Usage notes:</b>
+ </p>
+
<p>
- <b>Return type:</b>
- <codeph>bigint</codeph>
+ Each bucket contains values equal to or greater than the base value of that bucket
+ and less than the base value of the next bucket. For example, with
+ <codeph>width_bucket(8, 1, 10, 3)</codeph>, the bucket ranges are actually the 0th
+ "underflow bucket" with the range (-infinity to 0.999...), (1 to 3.999...), (4, to
+ 6.999...), (7 to 9.999...), and the "overflow bucket" with the range (10 to
+ infinity).
</p>
+
<p>
- <b>Added in:</b>
- <keyword keyref="impala31"/>. </p>
+ <b>Return type:</b> <codeph>BIGINT</codeph>
+ </p>
+
+ <p>
+ <b>Added in:</b> <keyword keyref="impala31"/>.
+ </p>
+
<p>
<b>Examples:</b>
</p>
- <p> The below function creates <codeph>3</codeph> buckets between the
- range of <codeph>1</codeph> and <codeph>20</codeph> with the bucket
- width of 6.333, and returns <codeph>2</codeph> for the bucket #2
- where the value <codeph>8</codeph> falls
- in:<codeblock>width_bucket(8, 1, 20, 3)</codeblock>
+
+ <p>
+ The below function creates <codeph>3</codeph> buckets between the range of
+ <codeph>1</codeph> and <codeph>20</codeph> with the bucket width of 6.333, and
+ returns <codeph>2</codeph> for the bucket #2 where the value <codeph>8</codeph>
+ falls in:
+<codeblock>width_bucket(
<TRUNCATED>
[07/10] impala git commit: [DOCS] Built-in Functions doc format
Changes
Posted by mi...@apache.org.
[DOCS] Built-in Functions doc format Changes
- The function titles were changed to upper case.
- The function titles no longer use <codeph>. <codeph> font appears
smaller than the <p> font.
- Return type were changed to upper case data types.
- Minor typos were fixed, such as extra commas and periods in titles.
- The indexterm dita elememts were removed. Indexterm was incomplete
and WIP. No plan to go ahead and implement it, so removed.
Change-Id: I797532463da8d29fe5bc7543cfdfb5b2b82db197
Reviewed-on: http://gerrit.cloudera.org:8080/11619
Tested-by: Impala Public Jenkins <im...@cloudera.com>
Reviewed-by: Michael Brown <mi...@cloudera.com>
Project: http://git-wip-us.apache.org/repos/asf/impala/repo
Commit: http://git-wip-us.apache.org/repos/asf/impala/commit/e8ee827a
Tree: http://git-wip-us.apache.org/repos/asf/impala/tree/e8ee827a
Diff: http://git-wip-us.apache.org/repos/asf/impala/diff/e8ee827a
Branch: refs/heads/master
Commit: e8ee827a6d39cf470f33a07e0f760ffc36775e1d
Parents: b0d0d73
Author: Alex Rodoni <ar...@cloudera.com>
Authored: Mon Oct 8 15:26:32 2018 -0700
Committer: Alex Rodoni <ar...@cloudera.com>
Committed: Wed Oct 10 18:18:09 2018 +0000
----------------------------------------------------------------------
docs/shared/impala_common.xml | 65 +-
docs/topics/impala_aggregate_functions.xml | 4 -
docs/topics/impala_analytic_functions.xml | 17 +-
docs/topics/impala_bit_functions.xml | 432 +++--
docs/topics/impala_conditional_functions.xml | 487 ++++--
docs/topics/impala_conversion_functions.xml | 872 ++--------
docs/topics/impala_datetime_functions.xml | 1825 +++++++++++++--------
docs/topics/impala_functions.xml | 2 +-
docs/topics/impala_math_functions.xml | 1301 +++++++++------
docs/topics/impala_misc_functions.xml | 184 ++-
docs/topics/impala_string_functions.xml | 919 +++++++----
11 files changed, 3383 insertions(+), 2725 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/shared/impala_common.xml
----------------------------------------------------------------------
diff --git a/docs/shared/impala_common.xml b/docs/shared/impala_common.xml
index ff0f449..45b7d87 100644
--- a/docs/shared/impala_common.xml
+++ b/docs/shared/impala_common.xml
@@ -1335,34 +1335,34 @@ drop database temp;
href="../topics/impala_s3.xml#s3"/> for details about working with S3
tables. </p>
- <p id="y2k38" rev="2.2.0">
- In Impala 2.2.0 and higher, built-in functions that accept or return integers representing <codeph>TIMESTAMP</codeph> values
- use the <codeph>BIGINT</codeph> type for parameters and return values, rather than <codeph>INT</codeph>.
- This change lets the date and time functions avoid an overflow error that would otherwise occur
- on January 19th, 2038 (known as the
- <xref href="http://en.wikipedia.org/wiki/Year_2038_problem" scope="external" format="html"><q>Year 2038 problem</q> or <q>Y2K38 problem</q></xref>).
- This change affects the <codeph>from_unixtime()</codeph> and <codeph>unix_timestamp()</codeph> functions.
- You might need to change application code that interacts with these functions, change the types of
- columns that store the return values, or add <codeph>CAST()</codeph> calls to SQL statements that
- call these functions.
- </p>
-
- <p id="timestamp_conversions">
- Impala automatically converts <codeph>STRING</codeph> literals of the
- correct format into <codeph>TIMESTAMP</codeph> values. Timestamp values
- are accepted in the format <codeph>"yyyy-MM-dd HH:mm:ss.SSSSSS"</codeph>,
- and can consist of just the date, or just the time, with or without the
- fractional second portion. For example, you can specify <codeph>TIMESTAMP</codeph>
- values such as <codeph>'1966-07-30'</codeph>, <codeph>'08:30:00'</codeph>,
- or <codeph>'1985-09-25 17:45:30.005'</codeph>.
- </p>
- <p>
- Leading zeroes are not required in the numbers representing the date
- component, such as month and date, or the time component, such as
- hour, minute, and second. For example, Impala accepts both
- <codeph>"2018-1-1 01:02:03"</codeph> and
- <codeph>"2018-01-01 1:2:3"</codeph> as valid.
- </p>
+ <p id="y2k38" rev="2.2.0"> In Impala 2.2.0 and higher, built-in functions
+ that accept or return integers representing <codeph>TIMESTAMP</codeph>
+ values use the <codeph>BIGINT</codeph> type for parameters and return
+ values, rather than <codeph>INT</codeph>. This change lets the date and
+ time functions avoid an overflow error that would otherwise occur on
+ January 19th, 2038 (known as the <xref
+ href="http://en.wikipedia.org/wiki/Year_2038_problem" scope="external"
+ format="html"><q>Year 2038 problem</q> or <q>Y2K38
+ problem</q></xref>). This change affects the
+ <codeph>FROM_UNIXTIME()</codeph> and <codeph>UNIX_TIMESTAMP()</codeph>
+ functions. You might need to change application code that interacts with
+ these functions, change the types of columns that store the return
+ values, or add <codeph>CAST()</codeph> calls to SQL statements that call
+ these functions. </p>
+
+ <p id="timestamp_conversions"> Impala automatically converts
+ <codeph>STRING</codeph> literals of the correct format into
+ <codeph>TIMESTAMP</codeph> values. Timestamp values are accepted in
+ the format <codeph>'yyyy-MM-dd HH:mm:ss.SSSSSS'</codeph>, and can
+ consist of just the date, or just the time, with or without the
+ fractional second portion. For example, you can specify
+ <codeph>TIMESTAMP</codeph> values such as
+ <codeph>'1966-07-30'</codeph>, <codeph>'08:30:00'</codeph>, or
+ <codeph>'1985-09-25 17:45:30.005'</codeph>. </p>
+ <p> Leading zeroes are not required in the numbers representing the date
+ component, such as month and date, or the time component, such as hour,
+ minute, and second. For example, Impala accepts both <codeph>'2018-1-1
+ 01:02:03'</codeph> and <codeph>'2018-01-01 1:2:3'</codeph> as valid. </p>
<p>
In <codeph>STRING</codeph> to <codeph>TIMESTAMP</codeph> conversions,
leading and trailing white spaces, such as a space, a tab, a newline, or
@@ -2056,10 +2056,11 @@ show functions in _impala_builtins like '*<varname>substring</varname>*';
</p>
<p id="datetime_function_chaining">
- <codeph>unix_timestamp()</codeph> and <codeph>from_unixtime()</codeph> are often used in combination to
- convert a <codeph>TIMESTAMP</codeph> value into a particular string format. For example:
-<codeblock xml:space="preserve">select from_unixtime(unix_timestamp(now() + interval 3 days),
- 'yyyy/MM/dd HH:mm') as yyyy_mm_dd_hh_mm;
+ <codeph>UNIX_TIMESTAMP()</codeph> and <codeph>FROM_UNIXTIME()</codeph>
+ are often used in combination to convert a <codeph>TIMESTAMP</codeph>
+ value into a particular string format. For example:
+ <codeblock xml:space="preserve">SELECT FROM_UNIXTIME(UNIX_TIMESTAMP(NOW() + interval 3 days),
+ 'yyyy/MM/dd HH:mm') AS yyyy_mm_dd_hh_mm;
+------------------+
| yyyy_mm_dd_hh_mm |
+------------------+
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_aggregate_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_aggregate_functions.xml b/docs/topics/impala_aggregate_functions.xml
index 1e01ad7..1d9118f 100644
--- a/docs/topics/impala_aggregate_functions.xml
+++ b/docs/topics/impala_aggregate_functions.xml
@@ -42,10 +42,6 @@ under the License.
<p conref="../shared/impala_common.xml#common/aggr3"/>
- <p>
- <indexterm audience="hidden">aggregate functions</indexterm>
- </p>
-
<p outputclass="toc"/>
</conbody>
</concept>
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_analytic_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_analytic_functions.xml b/docs/topics/impala_analytic_functions.xml
index 39d4fc5..f139927 100644
--- a/docs/topics/impala_analytic_functions.xml
+++ b/docs/topics/impala_analytic_functions.xml
@@ -43,16 +43,13 @@ under the License.
<conbody>
- <p rev="2.0.0">
- <indexterm audience="hidden">analytic functions</indexterm>
-
- <indexterm audience="hidden">window functions</indexterm>
- Analytic functions (also known as window functions) are a special category of built-in functions. Like
- aggregate functions, they examine the contents of multiple input rows to compute each output value. However,
- rather than being limited to one result value per <codeph>GROUP BY</codeph> group, they operate on
- <term>windows</term> where the input rows are ordered and grouped using flexible conditions expressed through
- an <codeph>OVER()</codeph> clause.
- </p>
+ <p rev="2.0.0"> Analytic functions (also known as window functions) are a
+ special category of built-in functions. Like aggregate functions, they
+ examine the contents of multiple input rows to compute each output value.
+ However, rather than being limited to one result value per <codeph>GROUP
+ BY</codeph> group, they operate on <term>windows</term> where the input
+ rows are ordered and grouped using flexible conditions expressed through
+ an <codeph>OVER()</codeph> clause. </p>
<p conref="../shared/impala_common.xml#common/added_in_20"/>
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_bit_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_bit_functions.xml b/docs/topics/impala_bit_functions.xml
index c42f834..35f584a 100644
--- a/docs/topics/impala_bit_functions.xml
+++ b/docs/topics/impala_bit_functions.xml
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?><!--
+<?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
@@ -20,7 +21,13 @@ under the License.
<concept id="bit_functions" rev="2.3.0">
<title>Impala Bit Functions</title>
- <titlealts audience="PDF"><navtitle>Bit Functions</navtitle></titlealts>
+
+ <titlealts audience="PDF">
+
+ <navtitle>Bit Functions</navtitle>
+
+ </titlealts>
+
<prolog>
<metadata>
<data name="Category" value="Impala"/>
@@ -35,32 +42,38 @@ under the License.
<conbody>
<p rev="2.3.0">
- Bit manipulation functions perform bitwise operations involved in scientific processing or computer science algorithms.
- For example, these functions include setting, clearing, or testing bits within an integer value, or changing the
- positions of bits with or without wraparound.
+ Bit manipulation functions perform bitwise operations involved in scientific processing or
+ computer science algorithms. For example, these functions include setting, clearing, or
+ testing bits within an integer value, or changing the positions of bits with or without
+ wraparound.
</p>
<p>
- If a function takes two integer arguments that are required to be of the same type, the smaller argument is promoted
- to the type of the larger one if required. For example, <codeph>BITAND(1,4096)</codeph> treats both arguments as
- <codeph>SMALLINT</codeph>, because 1 can be represented as a <codeph>TINYINT</codeph> but 4096 requires a <codeph>SMALLINT</codeph>.
+ If a function takes two integer arguments that are required to be of the same type, the
+ smaller argument is promoted to the type of the larger one if required. For example,
+ <codeph>BITAND(1,4096)</codeph> treats both arguments as <codeph>SMALLINT</codeph>,
+ because 1 can be represented as a <codeph>TINYINT</codeph> but 4096 requires a
+ <codeph>SMALLINT</codeph>.
</p>
<p>
- Remember that all Impala integer values are signed. Therefore, when dealing with binary values where the most significant
- bit is 1, the specified or returned values might be negative when represented in base 10.
+ Remember that all Impala integer values are signed. Therefore, when dealing with binary
+ values where the most significant bit is 1, the specified or returned values might be
+ negative when represented in base 10.
</p>
<p>
- Whenever any argument is <codeph>NULL</codeph>, either the input value, bit position, or number of shift or rotate positions,
- the return value from any of these functions is also <codeph>NULL</codeph>
+ Whenever any argument is <codeph>NULL</codeph>, either the input value, bit position, or
+ number of shift or rotate positions, the return value from any of these functions is also
+ <codeph>NULL</codeph>
</p>
<p conref="../shared/impala_common.xml#common/related_info"/>
<p>
- The bit functions operate on all the integral data types: <xref href="impala_int.xml#int"/>,
- <xref href="impala_bigint.xml#bigint"/>, <xref href="impala_smallint.xml#smallint"/>, and
+ The bit functions operate on all the integral data types:
+ <xref href="impala_int.xml#int"/>, <xref href="impala_bigint.xml#bigint"/>,
+ <xref href="impala_smallint.xml#smallint"/>, and
<xref href="impala_tinyint.xml#tinyint"/>.
</p>
@@ -72,51 +85,85 @@ under the License.
Impala supports the following bit functions:
</p>
-<!--
-bitand
-bitnot
-bitor
-bitxor
-countset
-getbit
-rotateleft
-rotateright
-setbit
-shiftleft
-shiftright
--->
+ <ul>
+ <li>
+ <xref href="#bit_functions/bitand">BITAND</xref>
+ </li>
- <dl>
+ <li>
+ <xref href="#bit_functions/bitnot">BITNOT</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/bitor">BITOR</xref>
+ </li>
+ <li>
+ <xref href="#bit_functions/bitxor">BITXOR</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/countset">COUNTSET</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/getbit">GETBIT</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/rotateleft">ROTATELEFT</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/rotateright">ROTATERIGHT</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/setbit">SETBIT</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/shiftleft">SHIFTLEFT</xref>
+ </li>
+
+ <li>
+ <xref href="#bit_functions/shiftright">SHIFTRIGHT</xref>
+ </li>
+ </ul>
+
+ <dl>
<dlentry id="bitand">
<dt>
- <codeph>bitand(integer_type a, same_type b)</codeph>
+ BITAND(integer_type a, same_type b)
</dt>
<dd>
- <indexterm audience="hidden">bitand() function</indexterm>
- <b>Purpose:</b> Returns an integer value representing the bits that are set to 1 in both of the arguments.
- If the arguments are of different sizes, the smaller is promoted to the type of the larger.
+ <b>Purpose:</b> Returns an integer value representing the bits that are set to 1 in
+ both of the arguments. If the arguments are of different sizes, the smaller is
+ promoted to the type of the larger.
<p>
- <b>Usage notes:</b> The <codeph>bitand()</codeph> function is equivalent to the <codeph>&</codeph> binary operator.
+ <b>Usage notes:</b> The <codeph>BITAND()</codeph> function is equivalent to the
+ <codeph>&</codeph> binary operator.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show the results of ANDing integer values.
- 255 contains all 1 bits in its lowermost 7 bits.
- 32767 contains all 1 bits in its lowermost 15 bits.
- <!--
+ The following examples show the results of ANDing integer values. 255 contains all 1
+ bits in its lowermost 7 bits. 32767 contains all 1 bits in its lowermost 15 bits.
+<!--
Negative numbers have a 1 in the sign bit and the value is the
<xref href="https://en.wikipedia.org/wiki/Two%27s_complement" scope="external" format="html">two's complement</xref>
of the positive equivalent.
-->
- You can use the <codeph>bin()</codeph> function to check the binary representation of any
- integer value, although the result is always represented as a 64-bit value.
- If necessary, the smaller argument is promoted to the
- type of the larger one.
+ You can use the <codeph>BIN()</codeph> function to check the binary representation
+ of any integer value, although the result is always represented as a 64-bit value.
+ If necessary, the smaller argument is promoted to the type of the larger one.
</p>
<codeblock>select bitand(255, 32767); /* 0000000011111111 & 0111111111111111 */
+--------------------+
@@ -160,23 +207,27 @@ select bitand(-1,15); /* 11111111 & 00001111 */
<dlentry id="bitnot">
<dt>
- <codeph>bitnot(integer_type a)</codeph>
+ BITNOT(integer_type a)
</dt>
<dd>
- <indexterm audience="hidden">bitnot() function</indexterm>
<b>Purpose:</b> Inverts all the bits of the input argument.
<p>
- <b>Usage notes:</b> The <codeph>bitnot()</codeph> function is equivalent to the <codeph>~</codeph> unary operator.
+ <b>Usage notes:</b> The <codeph>BITNOT()</codeph> function is equivalent to the
+ <codeph>~</codeph> unary operator.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- These examples illustrate what happens when you flip all the bits of an integer value.
- The sign always changes. The decimal representation is one different between the positive and
- negative values.
- <!--
+ These examples illustrate what happens when you flip all the bits of an integer
+ value. The sign always changes. The decimal representation is one different between
+ the positive and negative values.
+<!--
because negative values are represented as the
<xref href="https://en.wikipedia.org/wiki/Two%27s_complement" scope="external" format="html">two's complement</xref>
of the corresponding positive value.
@@ -217,19 +268,24 @@ select bitnot(-128); /* 10000000 -> 01111111 */
<dlentry id="bitor">
<dt>
- <codeph>bitor(integer_type a, same_type b)</codeph>
+ BITOR(integer_type a, same_type b)
</dt>
<dd>
- <indexterm audience="hidden">bitor() function</indexterm>
- <b>Purpose:</b> Returns an integer value representing the bits that are set to 1 in either of the arguments.
- If the arguments are of different sizes, the smaller is promoted to the type of the larger.
+ <b>Purpose:</b> Returns an integer value representing the bits that are set to 1 in
+ either of the arguments. If the arguments are of different sizes, the smaller is
+ promoted to the type of the larger.
<p>
- <b>Usage notes:</b> The <codeph>bitor()</codeph> function is equivalent to the <codeph>|</codeph> binary operator.
+ <b>Usage notes:</b> The <codeph>BITOR()</codeph> function is equivalent to the
+ <codeph>|</codeph> binary operator.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
The following examples show the results of ORing integer values.
</p>
@@ -261,24 +317,30 @@ select bitor(0,7); /* 00000000 | 00000111 */
<dlentry id="bitxor">
<dt>
- <codeph>bitxor(integer_type a, same_type b)</codeph>
+ BITXOR(integer_type a, same_type b)
</dt>
<dd>
- <indexterm audience="hidden">bitxor() function</indexterm>
- <b>Purpose:</b> Returns an integer value representing the bits that are set to 1 in one but not both of the arguments.
- If the arguments are of different sizes, the smaller is promoted to the type of the larger.
+ <b>Purpose:</b> Returns an integer value representing the bits that are set to 1 in
+ one but not both of the arguments. If the arguments are of different sizes, the
+ smaller is promoted to the type of the larger.
<p>
- <b>Usage notes:</b> The <codeph>bitxor()</codeph> function is equivalent to the <codeph>^</codeph> binary operator.
+ <b>Usage notes:</b> The <codeph>BITXOR()</codeph> function is equivalent to the
+ <codeph>^</codeph> binary operator.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show the results of XORing integer values.
- XORing a non-zero value with zero returns the non-zero value.
- XORing two identical values returns zero, because all the 1 bits from the first argument are also 1 bits in the second argument.
- XORing different non-zero values turns off some bits and leaves others turned on, based on whether the same bit is set in both arguments.
+ The following examples show the results of XORing integer values. XORing a non-zero
+ value with zero returns the non-zero value. XORing two identical values returns
+ zero, because all the 1 bits from the first argument are also 1 bits in the second
+ argument. XORing different non-zero values turns off some bits and leaves others
+ turned on, based on whether the same bit is set in both arguments.
</p>
<codeblock>select bitxor(0,15); /* 00000000 ^ 00001111 */
+---------------+
@@ -315,22 +377,30 @@ select bitxor(3,7); /* 00000011 ^ 00000111 */
<dlentry id="countset">
<dt>
- <codeph>countset(integer_type a [, int zero_or_one])</codeph>
+ COUNTSET(integer_type a [, INT zero_or_one])
</dt>
<dd>
- <indexterm audience="hidden">countset() function</indexterm>
- <b>Purpose:</b> By default, returns the number of 1 bits in the specified integer value.
- If the optional second argument is set to zero, it returns the number of 0 bits instead.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> By default, returns the number of 1 bits in the specified integer
+ value. If the optional second argument is set to zero, it returns the number of 0 bits
+ instead.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
In discussions of information theory, this operation is referred to as the
- <q><xref href="https://en.wikipedia.org/wiki/Hamming_weight" scope="external" format="html">population count</xref></q>
- or <q>popcount</q>.
+ <q><xref
+ href="https://en.wikipedia.org/wiki/Hamming_weight"
+ scope="external" format="html">population
+ count</xref></q> or <q>popcount</q>.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
The following examples show how to count the number of 1 bits in an integer value.
</p>
@@ -383,25 +453,29 @@ select countset(7,0); /* 00000111 = 5 0 bits; third argument can only be 0 or 1
<dlentry id="getbit">
<dt>
- <codeph>getbit(integer_type a, int position)</codeph>
+ GETBIT(integer_type a, INT position)
</dt>
<dd>
- <indexterm audience="hidden">getbit() function</indexterm>
- <b>Purpose:</b> Returns a 0 or 1 representing the bit at a
- specified position. The positions are numbered right to left, starting at zero.
- The position argument cannot be negative.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> Returns a 0 or 1 representing the bit at a specified position. The
+ positions are numbered right to left, starting at zero. The position argument cannot
+ be negative.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- When you use a literal input value, it is treated as an 8-bit, 16-bit,
- and so on value, the smallest type that is appropriate.
- The type of the input value limits the range of the positions.
- Cast the input value to the appropriate type if you need to
+ When you use a literal input value, it is treated as an 8-bit, 16-bit, and so on
+ value, the smallest type that is appropriate. The type of the input value limits the
+ range of the positions. Cast the input value to the appropriate type if you need to
ensure it is treated as a 64-bit, 32-bit, and so on value.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
The following examples show how to test a specific bit within an integer value.
</p>
@@ -457,33 +531,37 @@ select getbit(cast(-1 as int),25); /* 11111111111111111111111111111111 */
<dlentry id="rotateleft">
<dt>
- <codeph>rotateleft(integer_type a, int positions)</codeph>
+ ROTATELEFT(integer_type a, INT positions)
</dt>
<dd>
- <indexterm audience="hidden">rotateleft() function</indexterm>
- <b>Purpose:</b> Rotates an integer value left by a specified number of bits.
- As the most significant bit is taken out of the original value,
- if it is a 1 bit, it is <q>rotated</q> back to the least significant bit.
- Therefore, the final value has the same number of 1 bits as the original value,
- just in different positions.
- In computer science terms, this operation is a
- <q><xref href="https://en.wikipedia.org/wiki/Circular_shift" scope="external" format="html">circular shift</xref></q>.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> Rotates an integer value left by a specified number of bits. As the
+ most significant bit is taken out of the original value, if it is a 1 bit, it is
+ <q>rotated</q> back to the least significant bit. Therefore, the final value has the
+ same number of 1 bits as the original value, just in different positions. In computer
+ science terms, this operation is a
+ <q><xref
+ href="https://en.wikipedia.org/wiki/Circular_shift"
+ scope="external" format="html">circular
+ shift</xref></q>.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Specifying a second argument of zero leaves the original value unchanged.
- Rotating a -1 value by any number of positions still returns -1,
- because the original value has all 1 bits and all the 1 bits are
- preserved during rotation.
- Similarly, rotating a 0 value by any number of positions still returns 0.
- Rotating a value by the same number of bits as in the value returns the same value.
- Because this is a circular operation, the number of positions is not limited
- to the number of bits in the input value.
- For example, rotating an 8-bit value by 1, 9, 17, and so on positions returns an
- identical result in each case.
+ Specifying a second argument of zero leaves the original value unchanged. Rotating a
+ -1 value by any number of positions still returns -1, because the original value has
+ all 1 bits and all the 1 bits are preserved during rotation. Similarly, rotating a 0
+ value by any number of positions still returns 0. Rotating a value by the same
+ number of bits as in the value returns the same value. Because this is a circular
+ operation, the number of positions is not limited to the number of bits in the input
+ value. For example, rotating an 8-bit value by 1, 9, 17, and so on positions returns
+ an identical result in each case.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>select rotateleft(1,4); /* 00000001 -> 00010000 */
+------------------+
@@ -521,33 +599,37 @@ select rotateleft(-127,3); /* 10000001 -> 00001100 */
<dlentry id="rotateright">
<dt>
- <codeph>rotateright(integer_type a, int positions)</codeph>
+ ROTATERIGHT(integer_type a, INT positions)
</dt>
<dd>
- <indexterm audience="hidden">rotateright() function</indexterm>
- <b>Purpose:</b> Rotates an integer value right by a specified number of bits.
- As the least significant bit is taken out of the original value,
- if it is a 1 bit, it is <q>rotated</q> back to the most significant bit.
- Therefore, the final value has the same number of 1 bits as the original value,
- just in different positions.
- In computer science terms, this operation is a
- <q><xref href="https://en.wikipedia.org/wiki/Circular_shift" scope="external" format="html">circular shift</xref></q>.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> Rotates an integer value right by a specified number of bits. As the
+ least significant bit is taken out of the original value, if it is a 1 bit, it is
+ <q>rotated</q> back to the most significant bit. Therefore, the final value has the
+ same number of 1 bits as the original value, just in different positions. In computer
+ science terms, this operation is a
+ <q><xref
+ href="https://en.wikipedia.org/wiki/Circular_shift"
+ scope="external" format="html">circular
+ shift</xref></q>.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Specifying a second argument of zero leaves the original value unchanged.
- Rotating a -1 value by any number of positions still returns -1,
- because the original value has all 1 bits and all the 1 bits are
- preserved during rotation.
- Similarly, rotating a 0 value by any number of positions still returns 0.
- Rotating a value by the same number of bits as in the value returns the same value.
- Because this is a circular operation, the number of positions is not limited
- to the number of bits in the input value.
- For example, rotating an 8-bit value by 1, 9, 17, and so on positions returns an
- identical result in each case.
+ Specifying a second argument of zero leaves the original value unchanged. Rotating a
+ -1 value by any number of positions still returns -1, because the original value has
+ all 1 bits and all the 1 bits are preserved during rotation. Similarly, rotating a 0
+ value by any number of positions still returns 0. Rotating a value by the same
+ number of bits as in the value returns the same value. Because this is a circular
+ operation, the number of positions is not limited to the number of bits in the input
+ value. For example, rotating an 8-bit value by 1, 9, 17, and so on positions returns
+ an identical result in each case.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>select rotateright(16,4); /* 00010000 -> 00000001 */
+--------------------+
@@ -584,30 +666,31 @@ select rotateright(-127,3); /* 10000001 -> 00110000 */
<dlentry id="setbit">
<dt>
- <codeph>setbit(integer_type a, int position [, int zero_or_one])</codeph>
+ SETBIT(integer_type a, INT position [, INT zero_or_one])
</dt>
<dd>
- <indexterm audience="hidden">setbit() function</indexterm>
- <b>Purpose:</b> By default, changes a bit at a specified position to a 1, if it is not already.
- If the optional third argument is set to zero, the specified bit is set to 0 instead.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- If the bit at the specified position was already 1 (by default)
- or 0 (with a third argument of zero), the return value is
- the same as the first argument.
- The positions are numbered right to left, starting at zero.
- (Therefore, the return value could be different from the first argument
- even if the position argument is zero.)
- The position argument cannot be negative.
+ <b>Purpose:</b> By default, changes a bit at a specified position to a 1, if it is not
+ already. If the optional third argument is set to zero, the specified bit is set to 0
+ instead.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ If the bit at the specified position was already 1 (by default) or 0 (with a third
+ argument of zero), the return value is the same as the first argument. The positions
+ are numbered right to left, starting at zero. (Therefore, the return value could be
+ different from the first argument even if the position argument is zero.) The position
+ argument cannot be negative.
<p>
- When you use a literal input value, it is treated as an 8-bit, 16-bit,
- and so on value, the smallest type that is appropriate.
- The type of the input value limits the range of the positions.
- Cast the input value to the appropriate type if you need to
+ When you use a literal input value, it is treated as an 8-bit, 16-bit, and so on
+ value, the smallest type that is appropriate. The type of the input value limits the
+ range of the positions. Cast the input value to the appropriate type if you need to
ensure it is treated as a 64-bit, 32-bit, and so on value.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>select setbit(0,0); /* 00000000 -> 00000001 */
+--------------+
@@ -668,32 +751,39 @@ select setbit(7,2,0); /* 00000111 -> 00000011; third argument of 0 clears instea
<dlentry id="shiftleft">
<dt>
- <codeph>shiftleft(integer_type a, int positions)</codeph>
+ SHIFTLEFT(integer_type a, INT positions)
</dt>
<dd>
- <indexterm audience="hidden">shiftleft() function</indexterm>
- <b>Purpose:</b> Shifts an integer value left by a specified number of bits.
- As the most significant bit is taken out of the original value,
- it is discarded and the least significant bit becomes 0.
- In computer science terms, this operation is a <q><xref href="https://en.wikipedia.org/wiki/Logical_shift" scope="external" format="html">logical shift</xref></q>.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> Shifts an integer value left by a specified number of bits. As the
+ most significant bit is taken out of the original value, it is discarded and the least
+ significant bit becomes 0. In computer science terms, this operation is a
+ <q><xref
+ href="https://en.wikipedia.org/wiki/Logical_shift"
+ scope="external" format="html">logical
+ shift</xref></q>.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- The final value has either the same number of 1 bits as the original value, or fewer.
- Shifting an 8-bit value by 8 positions, a 16-bit value by 16 positions, and so on produces
- a result of zero.
+ The final value has either the same number of 1 bits as the original value, or
+ fewer. Shifting an 8-bit value by 8 positions, a 16-bit value by 16 positions, and
+ so on produces a result of zero.
</p>
+
<p>
- Specifying a second argument of zero leaves the original value unchanged.
- Shifting any value by 0 returns the original value.
- Shifting any value by 1 is the same as multiplying it by 2,
- as long as the value is small enough; larger values eventually
- become negative when shifted, as the sign bit is set.
- Starting with the value 1 and shifting it left by N positions gives
- the same result as 2 to the Nth power, or <codeph>pow(2,<varname>N</varname>)</codeph>.
+ Specifying a second argument of zero leaves the original value unchanged. Shifting
+ any value by 0 returns the original value. Shifting any value by 1 is the same as
+ multiplying it by 2, as long as the value is small enough; larger values eventually
+ become negative when shifted, as the sign bit is set. Starting with the value 1 and
+ shifting it left by N positions gives the same result as 2 to the Nth power, or
+ <codeph>POW(2,<varname>N</varname>)</codeph>.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>select shiftleft(1,0); /* 00000001 -> 00000001 */
+-----------------+
@@ -744,29 +834,36 @@ select shiftleft(-1,4); /* 11111111 -> 11110000 */
<dlentry id="shiftright">
<dt>
- <codeph>shiftright(integer_type a, int positions)</codeph>
+ SHIFTRIGHT(integer_type a, INT positions)
</dt>
<dd>
- <indexterm audience="hidden">shiftright() function</indexterm>
- <b>Purpose:</b> Shifts an integer value right by a specified number of bits.
- As the least significant bit is taken out of the original value,
- it is discarded and the most significant bit becomes 0.
- In computer science terms, this operation is a <q><xref href="https://en.wikipedia.org/wiki/Logical_shift" scope="external" format="html">logical shift</xref></q>.
- <p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+ <b>Purpose:</b> Shifts an integer value right by a specified number of bits. As the
+ least significant bit is taken out of the original value, it is discarded and the most
+ significant bit becomes 0. In computer science terms, this operation is a
+ <q><xref
+ href="https://en.wikipedia.org/wiki/Logical_shift"
+ scope="external" format="html">logical
+ shift</xref></q>.
+ <p
+ conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Therefore, the final value has either the same number of 1 bits as the original value, or fewer.
- Shifting an 8-bit value by 8 positions, a 16-bit value by 16 positions, and so on produces
- a result of zero.
+ Therefore, the final value has either the same number of 1 bits as the original
+ value, or fewer. Shifting an 8-bit value by 8 positions, a 16-bit value by 16
+ positions, and so on produces a result of zero.
</p>
+
<p>
- Specifying a second argument of zero leaves the original value unchanged.
- Shifting any value by 0 returns the original value.
- Shifting any positive value right by 1 is the same as dividing it by 2.
- Negative values become positive when shifted right.
+ Specifying a second argument of zero leaves the original value unchanged. Shifting
+ any value by 0 returns the original value. Shifting any positive value right by 1 is
+ the same as dividing it by 2. Negative values become positive when shifted right.
</p>
+
<p conref="../shared/impala_common.xml#common/return_type_same"/>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>select shiftright(16,0); /* 00010000 -> 00010000 */
+-------------------+
@@ -806,7 +903,8 @@ select shiftright(-1,5); /* 11111111 -> 00000111 */
</dd>
</dlentry>
-
</dl>
+
</conbody>
+
</concept>
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_conditional_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_conditional_functions.xml b/docs/topics/impala_conditional_functions.xml
index 45717e1..106c518 100644
--- a/docs/topics/impala_conditional_functions.xml
+++ b/docs/topics/impala_conditional_functions.xml
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?><!--
+<?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
@@ -20,7 +21,13 @@ under the License.
<concept id="conditional_functions">
<title>Impala Conditional Functions</title>
- <titlealts audience="PDF"><navtitle>Conditional Functions</navtitle></titlealts>
+
+ <titlealts audience="PDF">
+
+ <navtitle>Conditional Functions</navtitle>
+
+ </titlealts>
+
<prolog>
<metadata>
<data name="Category" value="Impala"/>
@@ -35,34 +42,115 @@ under the License.
<conbody>
<p>
- Impala supports the following conditional functions for testing equality, comparison operators, and nullity:
+ Impala supports the following conditional functions for testing equality, comparison
+ operators, and nullity:
</p>
+ <ul>
+ <li>
+ <xref href="#conditional_functions/case">CASE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/case2">CASE2</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/coalesce">COALESCE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/decode">DECODE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/if">IF</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/ifnull">IFNULL</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/isfalse">ISFALSE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/isnotfalse">ISNOTFALSE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/isnottrue">ISNOTTRUE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/isnull">ISNULL</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/istrue">ISTRUE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/nonnullvalue">NONNULLVALUE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/nullif">NULLIF</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/nullifzero">NULLIFZERO</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/nullvalue">NULLVALUE</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/nvl">NVL</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/nvl2">NVL2</xref>
+ </li>
+
+ <li>
+ <xref href="#conditional_functions/zeroifnull">ZEROIFNULL</xref>
+ </li>
+ </ul>
+
<dl>
<dlentry id="case">
<dt>
- <codeph>CASE a WHEN b THEN c [WHEN d THEN e]... [ELSE f] END</codeph>
+ CASE a WHEN b THEN c [WHEN d THEN e]... [ELSE f] END
</dt>
<dd>
- <indexterm audience="hidden">CASE expression</indexterm>
- <b>Purpose:</b> Compares an expression to one or more possible values, and returns a corresponding result
- when a match is found.
- <p conref="../shared/impala_common.xml#common/return_same_type"/>
+ <b>Purpose:</b> Compares an expression to one or more possible values, and returns a
+ corresponding result when a match is found.
+ <p
+ conref="../shared/impala_common.xml#common/return_same_type"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- In this form of the <codeph>CASE</codeph> expression, the initial value <codeph>A</codeph>
- being evaluated for each row it typically a column reference, or an expression involving
- a column. This form can only compare against a set of specified values, not ranges,
- multi-value comparisons such as <codeph>BETWEEN</codeph> or <codeph>IN</codeph>,
- regular expressions, or <codeph>NULL</codeph>.
+ In this form of the <codeph>CASE</codeph> expression, the initial value
+ <codeph>A</codeph> being evaluated for each row it typically a column reference, or
+ an expression involving a column. This form can only compare against a set of
+ specified values, not ranges, multi-value comparisons such as
+ <codeph>BETWEEN</codeph> or <codeph>IN</codeph>, regular expressions, or
+ <codeph>NULL</codeph>.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- Although this example is split across multiple lines, you can put any or all parts of a <codeph>CASE</codeph> expression
- on a single line, with no punctuation or other separators between the <codeph>WHEN</codeph>,
- <codeph>ELSE</codeph>, and <codeph>END</codeph> clauses.
+ Although this example is split across multiple lines, you can put any or all parts
+ of a <codeph>CASE</codeph> expression on a single line, with no punctuation or other
+ separators between the <codeph>WHEN</codeph>, <codeph>ELSE</codeph>, and
+ <codeph>END</codeph> clauses.
</p>
<codeblock>select case x
when 1 then 'one'
@@ -79,52 +167,61 @@ under the License.
<dlentry id="case2">
<dt>
- <codeph>CASE WHEN a THEN b [WHEN c THEN d]... [ELSE e] END</codeph>
+ CASE WHEN a THEN b [WHEN c THEN d]... [ELSE e] END
</dt>
<dd>
- <indexterm audience="hidden">CASE expression</indexterm>
- <b>Purpose:</b> Tests whether any of a sequence of expressions is true, and returns a corresponding
- result for the first true expression.
- <p conref="../shared/impala_common.xml#common/return_same_type"/>
+ <b>Purpose:</b> Tests whether any of a sequence of expressions is true, and returns a
+ corresponding result for the first true expression.
+ <p
+ conref="../shared/impala_common.xml#common/return_same_type"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- <codeph>CASE</codeph> expressions without an initial test value have more flexibility.
- For example, they can test different columns in different <codeph>WHEN</codeph> clauses,
- or use comparison operators such as <codeph>BETWEEN</codeph>, <codeph>IN</codeph> and <codeph>IS NULL</codeph>
- rather than comparing against discrete values.
+ <codeph>CASE</codeph> expressions without an initial test value have more
+ flexibility. For example, they can test different columns in different
+ <codeph>WHEN</codeph> clauses, or use comparison operators such as
+ <codeph>BETWEEN</codeph>, <codeph>IN</codeph> and <codeph>IS NULL</codeph> rather
+ than comparing against discrete values.
</p>
+
<p>
<codeph>CASE</codeph> expressions are often the foundation of long queries that
- summarize and format results for easy-to-read reports. For example, you might
- use a <codeph>CASE</codeph> function call to turn values from a numeric column
- into category strings corresponding to integer values, or labels such as <q>Small</q>,
- <q>Medium</q> and <q>Large</q> based on ranges. Then subsequent parts of the
- query might aggregate based on the transformed values, such as how many
- values are classified as small, medium, or large. You can also use <codeph>CASE</codeph>
- to signal problems with out-of-bounds values, <codeph>NULL</codeph> values,
- and so on.
+ summarize and format results for easy-to-read reports. For example, you might use a
+ <codeph>CASE</codeph> function call to turn values from a numeric column into
+ category strings corresponding to integer values, or labels such as <q>Small</q>,
+ <q>Medium</q> and <q>Large</q> based on ranges. Then subsequent parts of the query
+ might aggregate based on the transformed values, such as how many values are
+ classified as small, medium, or large. You can also use <codeph>CASE</codeph> to
+ signal problems with out-of-bounds values, <codeph>NULL</codeph> values, and so on.
</p>
+
<p>
By using operators such as <codeph>OR</codeph>, <codeph>IN</codeph>,
- <codeph>REGEXP</codeph>, and so on in <codeph>CASE</codeph> expressions,
- you can build extensive tests and transformations into a single query.
- Therefore, applications that construct SQL statements often rely heavily on <codeph>CASE</codeph>
- calls in the generated SQL code.
+ <codeph>REGEXP</codeph>, and so on in <codeph>CASE</codeph> expressions, you can
+ build extensive tests and transformations into a single query. Therefore,
+ applications that construct SQL statements often rely heavily on
+ <codeph>CASE</codeph> calls in the generated SQL code.
</p>
+
<p>
- Because this flexible form of the <codeph>CASE</codeph> expressions allows you to perform
- many comparisons and call multiple functions when evaluating each row, be careful applying
- elaborate <codeph>CASE</codeph> expressions to queries that process large amounts of data.
- For example, when practical, evaluate and transform values through <codeph>CASE</codeph>
- after applying operations such as aggregations that reduce the size of the result set;
- transform numbers to strings after performing joins with the original numeric values.
+ Because this flexible form of the <codeph>CASE</codeph> expressions allows you to
+ perform many comparisons and call multiple functions when evaluating each row, be
+ careful applying elaborate <codeph>CASE</codeph> expressions to queries that process
+ large amounts of data. For example, when practical, evaluate and transform values
+ through <codeph>CASE</codeph> after applying operations such as aggregations that
+ reduce the size of the result set; transform numbers to strings after performing
+ joins with the original numeric values.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- Although this example is split across multiple lines, you can put any or all parts of a <codeph>CASE</codeph> expression
- on a single line, with no punctuation or other separators between the <codeph>WHEN</codeph>,
- <codeph>ELSE</codeph>, and <codeph>END</codeph> clauses.
+ Although this example is split across multiple lines, you can put any or all parts
+ of a <codeph>CASE</codeph> expression on a single line, with no punctuation or other
+ separators between the <codeph>WHEN</codeph>, <codeph>ELSE</codeph>, and
+ <codeph>END</codeph> clauses.
</p>
<codeblock>select case
when dayname(now()) in ('Saturday','Sunday') then 'result undefined on weekends'
@@ -142,14 +239,15 @@ under the License.
<dlentry id="coalesce">
<dt>
- <codeph>coalesce(type v1, type v2, ...)</codeph>
+ COALESCE(type v1, type v2, ...)
</dt>
<dd>
- <indexterm audience="hidden">coalesce() function</indexterm>
- <b>Purpose:</b> Returns the first specified argument that is not <codeph>NULL</codeph>, or
- <codeph>NULL</codeph> if all arguments are <codeph>NULL</codeph>.
- <p conref="../shared/impala_common.xml#common/return_same_type"/>
+ <b>Purpose:</b> Returns the first specified argument that is not
+ <codeph>NULL</codeph>, or <codeph>NULL</codeph> if all arguments are
+ <codeph>NULL</codeph>.
+ <p
+ conref="../shared/impala_common.xml#common/return_same_type"/>
</dd>
</dlentry>
@@ -157,32 +255,40 @@ under the License.
<dlentry rev="2.0.0" id="decode">
<dt>
- <codeph>decode(type expression, type search1, type result1 [, type search2, type result2 ...] [, type
- default] )</codeph>
+ DECODE(type expression, type search1, type result1 [, type search2, type result2 ...]
+ [, type default] )
</dt>
<dd>
- <indexterm audience="hidden">decode() function</indexterm>
- <b>Purpose:</b> Compares an expression to one or more possible values, and returns a corresponding result
- when a match is found.
- <p conref="../shared/impala_common.xml#common/return_same_type"/>
+ <b>Purpose:</b> Compares an expression to one or more possible values, and returns a
+ corresponding result when a match is found.
+ <p
+ conref="../shared/impala_common.xml#common/return_same_type"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
Can be used as shorthand for a <codeph>CASE</codeph> expression.
</p>
+
<p>
- The original expression and the search expressions must of the same type or convertible types. The
- result expression can be a different type, but all result expressions must be of the same type.
+ The original expression and the search expressions must of the same type or
+ convertible types. The result expression can be a different type, but all result
+ expressions must be of the same type.
</p>
+
<p>
- Returns a successful match If the original expression is <codeph>NULL</codeph> and a search expression
- is also <codeph>NULL</codeph>. the
+ Returns a successful match If the original expression is <codeph>NULL</codeph> and a
+ search expression is also <codeph>NULL</codeph>. the
</p>
+
<p>
- Returns <codeph>NULL</codeph> if the final <codeph>default</codeph> value is omitted and none of the
- search expressions match the original expression.
+ Returns <codeph>NULL</codeph> if the final <codeph>default</codeph> value is omitted
+ and none of the search expressions match the original expression.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
The following example translates numeric day values into descriptive names:
</p>
@@ -197,13 +303,12 @@ under the License.
<dlentry id="if">
<dt>
- <codeph>if(boolean condition, type ifTrue, type ifFalseOrNull)</codeph>
+ IF(BOOLEAN condition, type ifTrue, type ifFalseOrNull)
</dt>
<dd>
- <indexterm audience="hidden">if() function</indexterm>
- <b>Purpose:</b> Tests an expression and returns a corresponding result depending on whether the result is
- true, false, or <codeph>NULL</codeph>.
+ <b>Purpose:</b> Tests an expression and returns a corresponding result depending on
+ whether the result is true, false, or <codeph>NULL</codeph>.
<p>
<b>Return type:</b> Same as the <codeph>ifTrue</codeph> argument value
</p>
@@ -214,13 +319,12 @@ under the License.
<dlentry rev="1.3.0" id="ifnull">
<dt>
- <codeph>ifnull(type a, type ifNull)</codeph>
+ IFNULL(type a, type ifNull)
</dt>
<dd>
- <indexterm audience="hidden">isnull() function</indexterm>
- <b>Purpose:</b> Alias for the <codeph>isnull()</codeph> function, with the same behavior. To simplify
- porting SQL with vendor extensions to Impala.
+ <b>Purpose:</b> Alias for the <codeph>ISNULL()</codeph> function, with the same
+ behavior. To simplify porting SQL with vendor extensions to Impala.
<p conref="../shared/impala_common.xml#common/added_in_130"/>
</dd>
@@ -229,19 +333,24 @@ under the License.
<dlentry id="isfalse" rev="2.2.0">
<dt>
- <codeph>isfalse(<varname>boolean</varname>)</codeph>
+ ISFALSE(BOOLEAN expression)
</dt>
<dd>
- <indexterm audience="hidden">isfalse() function</indexterm>
<b>Purpose:</b> Tests if a Boolean expression is <codeph>false</codeph> or not.
- Returns <codeph>true</codeph> if so.
- If the argument is <codeph>NULL</codeph>, returns <codeph>false</codeph>.
- Identical to <codeph>isnottrue()</codeph>, except it returns the opposite value for a <codeph>NULL</codeph> argument.
- <p conref="../shared/impala_common.xml#common/return_type_boolean"/>
+ Returns <codeph>true</codeph> if so. If the argument is <codeph>NULL</codeph>, returns
+ <codeph>false</codeph>. Similar to <codeph>ISNOTTRUE()</codeph>, except it returns the
+ opposite value for a <codeph>NULL</codeph> argument.
+ <p
+ conref="../shared/impala_common.xml#common/return_type_boolean"/>
+
<p conref="../shared/impala_common.xml#common/added_in_220"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"/>
+
+ <p
+ conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"
+ />
</dd>
</dlentry>
@@ -249,20 +358,27 @@ under the License.
<dlentry id="isnotfalse" rev="2.2.0">
<dt>
- <codeph>isnotfalse(<varname>boolean</varname>)</codeph>
+ ISNOTFALSE(BOOLEAN expression)
</dt>
<dd>
- <indexterm audience="hidden">isnotfalse() function</indexterm>
- <b>Purpose:</b> Tests if a Boolean expression is not <codeph>false</codeph> (that is, either <codeph>true</codeph> or <codeph>NULL</codeph>).
- Returns <codeph>true</codeph> if so.
- If the argument is <codeph>NULL</codeph>, returns <codeph>true</codeph>.
- Identical to <codeph>istrue()</codeph>, except it returns the opposite value for a <codeph>NULL</codeph> argument.
- <p conref="../shared/impala_common.xml#common/return_type_boolean"/>
+ <b>Purpose:</b> Tests if a Boolean expression is not <codeph>false</codeph> (that is,
+ either <codeph>true</codeph> or <codeph>NULL</codeph>). Returns <codeph>true</codeph>
+ if so. If the argument is <codeph>NULL</codeph>, returns <codeph>true</codeph>.
+ Similar to <codeph>ISTRUE()</codeph>, except it returns the opposite value for a
+ <codeph>NULL</codeph> argument.
+ <p
+ conref="../shared/impala_common.xml#common/return_type_boolean"/>
+
<p conref="../shared/impala_common.xml#common/for_compatibility_only"/>
+
<p conref="../shared/impala_common.xml#common/added_in_220"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"/>
+
+ <p
+ conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"
+ />
</dd>
</dlentry>
@@ -270,19 +386,25 @@ under the License.
<dlentry id="isnottrue" rev="2.2.0">
<dt>
- <codeph>isnottrue(<varname>boolean</varname>)</codeph>
+ ISNOTTRUE(BOOLEAN expression)
</dt>
<dd>
- <indexterm audience="hidden">isnottrue() function</indexterm>
- <b>Purpose:</b> Tests if a Boolean expression is not <codeph>true</codeph> (that is, either <codeph>false</codeph> or <codeph>NULL</codeph>).
- Returns <codeph>true</codeph> if so.
- If the argument is <codeph>NULL</codeph>, returns <codeph>true</codeph>.
- Identical to <codeph>isfalse()</codeph>, except it returns the opposite value for a <codeph>NULL</codeph> argument.
- <p conref="../shared/impala_common.xml#common/return_type_boolean"/>
+ <b>Purpose:</b> Tests if a Boolean expression is not <codeph>true</codeph> (that is,
+ either <codeph>false</codeph> or <codeph>NULL</codeph>). Returns <codeph>true</codeph>
+ if so. If the argument is <codeph>NULL</codeph>, returns <codeph>true</codeph>.
+ Similar to <codeph>ISFALSE()</codeph>, except it returns the opposite value for a
+ <codeph>NULL</codeph> argument.
+ <p
+ conref="../shared/impala_common.xml#common/return_type_boolean"/>
+
<p conref="../shared/impala_common.xml#common/added_in_220"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"/>
+
+ <p
+ conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"
+ />
</dd>
</dlentry>
@@ -290,18 +412,19 @@ under the License.
<dlentry id="isnull">
<dt>
- <codeph>isnull(type a, type ifNull)</codeph>
+ ISNULL(type a, type ifNull)
</dt>
<dd>
- <indexterm audience="hidden">isnull() function</indexterm>
- <b>Purpose:</b> Tests if an expression is <codeph>NULL</codeph>, and returns the expression result value
- if not. If the first argument is <codeph>NULL</codeph>, returns the second argument.
+ <b>Purpose:</b> Tests if an expression is <codeph>NULL</codeph>, and returns the
+ expression result value if not. If the first argument is <codeph>NULL</codeph>,
+ returns the second argument.
<p>
- <b>Compatibility notes:</b> Equivalent to the <codeph>nvl()</codeph> function from Oracle Database or
- <codeph>ifnull()</codeph> from MySQL. The <codeph>nvl()</codeph> and <codeph>ifnull()</codeph>
- functions are also available in Impala.
+ <b>Compatibility notes:</b> Equivalent to the <codeph>NVL()</codeph> function from
+ Oracle Database or <codeph>IFNULL()</codeph> from MySQL. The <codeph>NVL()</codeph>
+ and <codeph>IFNULL()</codeph> functions are also available in Impala.
</p>
+
<p>
<b>Return type:</b> Same as the first argument value
</p>
@@ -312,20 +435,26 @@ under the License.
<dlentry id="istrue" rev="2.2.0">
<dt>
- <codeph>istrue(<varname>boolean</varname>)</codeph>
+ ISTRUE(BOOLEAN expression)
</dt>
<dd>
- <indexterm audience="hidden">istrue() function</indexterm>
- <b>Purpose:</b> Tests if a Boolean expression is <codeph>true</codeph> or not.
- Returns <codeph>true</codeph> if so.
- If the argument is <codeph>NULL</codeph>, returns <codeph>false</codeph>.
- Identical to <codeph>isnotfalse()</codeph>, except it returns the opposite value for a <codeph>NULL</codeph> argument.
- <p conref="../shared/impala_common.xml#common/return_type_boolean"/>
+ <b>Purpose:</b> Tests if a Boolean expression is <codeph>true</codeph> or not. Returns
+ <codeph>true</codeph> if so. If the argument is <codeph>NULL</codeph>, returns
+ <codeph>false</codeph>. Similar to <codeph>ISNOTFALSE()</codeph>, except it returns
+ the opposite value for a <codeph>NULL</codeph> argument.
+ <p
+ conref="../shared/impala_common.xml#common/return_type_boolean"/>
+
<p conref="../shared/impala_common.xml#common/for_compatibility_only"/>
+
<p conref="../shared/impala_common.xml#common/added_in_220"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"/>
+
+ <p
+ conref="../shared/impala_common.xml#common/boolean_functions_vs_expressions"
+ />
</dd>
</dlentry>
@@ -333,16 +462,17 @@ under the License.
<dlentry id="nonnullvalue" rev="2.2.0">
<dt>
- <codeph>nonnullvalue(<varname>expression</varname>)</codeph>
+ NONNULLVALUE(type expression)
</dt>
<dd>
- <indexterm audience="hidden">function</indexterm>
<b>Purpose:</b> Tests if an expression (of any type) is <codeph>NULL</codeph> or not.
- Returns <codeph>false</codeph> if so.
- The converse of <codeph>nullvalue()</codeph>.
- <p conref="../shared/impala_common.xml#common/return_type_boolean"/>
+ Returns <codeph>false</codeph> if so. The converse of <codeph>NULLVALUE()</codeph>.
+ <p
+ conref="../shared/impala_common.xml#common/return_type_boolean"/>
+
<p conref="../shared/impala_common.xml#common/for_compatibility_only"/>
+
<p conref="../shared/impala_common.xml#common/added_in_220"/>
</dd>
@@ -351,35 +481,38 @@ under the License.
<dlentry rev="1.3.0" id="nullif">
<dt>
- <codeph>nullif(<varname>expr1</varname>,<varname>expr2</varname>)</codeph>
+ NULLIF(type expr1, type expr2)
</dt>
<dd>
- <indexterm audience="hidden">nullif() function</indexterm>
- <b>Purpose:</b> Returns <codeph>NULL</codeph> if the two specified arguments are equal. If the specified
- arguments are not equal, returns the value of <varname>expr1</varname>. The data types of the expressions
- must be compatible, according to the conversion rules from <xref href="impala_datatypes.xml#datatypes"/>.
- You cannot use an expression that evaluates to <codeph>NULL</codeph> for <varname>expr1</varname>; that
- way, you can distinguish a return value of <codeph>NULL</codeph> from an argument value of
- <codeph>NULL</codeph>, which would never match <varname>expr2</varname>.
+ <b>Purpose:</b> Returns <codeph>NULL</codeph> if the two specified arguments are
+ equal. If the specified arguments are not equal, returns the value of
+ <varname>expr1</varname>. The data types of the expressions must be compatible,
+ according to the conversion rules from <xref href="impala_datatypes.xml#datatypes"/>.
+ You cannot use an expression that evaluates to <codeph>NULL</codeph> for
+ <varname>expr1</varname>; that way, you can distinguish a return value of
+ <codeph>NULL</codeph> from an argument value of <codeph>NULL</codeph>, which would
+ never match <varname>expr2</varname>.
<p>
- <b>Usage notes:</b> This function is effectively shorthand for a <codeph>CASE</codeph> expression of
- the form:
+ <b>Usage notes:</b> This function is effectively shorthand for a
+ <codeph>CASE</codeph> expression of the form:
</p>
<codeblock>CASE
WHEN <varname>expr1</varname> = <varname>expr2</varname> THEN NULL
ELSE <varname>expr1</varname>
END</codeblock>
<p>
- It is commonly used in division expressions, to produce a <codeph>NULL</codeph> result instead of a
- divide-by-zero error when the divisor is equal to zero:
+ It is commonly used in division expressions, to produce a <codeph>NULL</codeph>
+ result instead of a divide-by-zero error when the divisor is equal to zero:
</p>
<codeblock>select 1.0 / nullif(c1,0) as reciprocal from t1;</codeblock>
<p>
- You might also use it for compatibility with other database systems that support the same
- <codeph>NULLIF()</codeph> function.
+ You might also use it for compatibility with other database systems that support the
+ same <codeph>NULLIF()</codeph> function.
</p>
+
<p conref="../shared/impala_common.xml#common/return_same_type"/>
+
<p conref="../shared/impala_common.xml#common/added_in_130"/>
</dd>
@@ -388,21 +521,22 @@ END</codeblock>
<dlentry rev="1.3.0" id="nullifzero">
<dt>
- <codeph>nullifzero(<varname>numeric_expr</varname>)</codeph>
+ NULLIFZERO(type numeric_expr)
</dt>
- <dd><b>Purpose:</b> Returns <codeph>NULL</codeph> if the numeric
- expression evaluates to 0, otherwise returns the result of the
- expression.
+ <dd>
+ <b>Purpose:</b> Returns <codeph>NULL</codeph> if the numeric expression evaluates to
+ 0, otherwise returns the result of the expression.
<p>
- <b>Usage notes:</b> Used to avoid error conditions such as
- divide-by-zero in numeric calculations. Serves as shorthand for a
- more elaborate <codeph>CASE</codeph> expression, to simplify porting
- SQL with vendor extensions to Impala.
+ <b>Usage notes:</b> Used to avoid error conditions such as divide-by-zero in numeric
+ calculations. Serves as shorthand for a more elaborate <codeph>CASE</codeph>
+ expression, to simplify porting SQL with vendor extensions to Impala.
</p>
- <p><b>Return type:</b>
- Same type as the input argument
+
+ <p>
+ <b>Return type:</b> Same type as the input argument
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_130"/>
</dd>
@@ -411,16 +545,17 @@ END</codeblock>
<dlentry id="nullvalue" rev="2.2.0">
<dt>
- <codeph>nullvalue(<varname>expression</varname>)</codeph>
+ NULLVALUE(type expression)
</dt>
<dd>
- <indexterm audience="hidden">function</indexterm>
<b>Purpose:</b> Tests if an expression (of any type) is <codeph>NULL</codeph> or not.
- Returns <codeph>true</codeph> if so.
- The converse of <codeph>nonnullvalue()</codeph>.
- <p conref="../shared/impala_common.xml#common/return_type_boolean"/>
+ Returns <codeph>true</codeph> if so. The converse of <codeph>NONNULLVALUE()</codeph>.
+ <p
+ conref="../shared/impala_common.xml#common/return_type_boolean"/>
+
<p conref="../shared/impala_common.xml#common/for_compatibility_only"/>
+
<p conref="../shared/impala_common.xml#common/added_in_220"/>
</dd>
@@ -429,18 +564,19 @@ END</codeblock>
<dlentry id="nvl" rev="1.1">
<dt>
- <codeph>nvl(type a, type ifNull)</codeph>
+ NVL(type a, type ifNull)
</dt>
<dd>
- <indexterm audience="hidden">nvl() function</indexterm>
- <b>Purpose:</b> Alias for the <codeph>isnull()</codeph> function. Tests if an expression is
- <codeph>NULL</codeph>, and returns the expression result value if not. If the first argument is
- <codeph>NULL</codeph>, returns the second argument. Equivalent to the <codeph>nvl()</codeph> function
- from Oracle Database or <codeph>ifnull()</codeph> from MySQL.
+ <b>Purpose:</b> Alias for the <codeph>ISNULL()</codeph> function. Tests if an
+ expression is <codeph>NULL</codeph>, and returns the expression result value if not.
+ If the first argument is <codeph>NULL</codeph>, returns the second argument.
+ Equivalent to the <codeph>NVL()</codeph> function from Oracle Database or
+ <codeph>IFNULL()</codeph> from MySQL.
<p>
<b>Return type:</b> Same as the first argument value
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_11"/>
</dd>
@@ -449,27 +585,29 @@ END</codeblock>
<dlentry id="nvl2" rev="2.9.0 IMPALA-5030">
<dt>
- <codeph>nvl2(type a, type ifNull, type ifNotNull)</codeph>
+ NVL2(type a, type ifNull, type ifNotNull)
</dt>
<dd>
- <indexterm audience="hidden">nvl2() function</indexterm>
- <b>Purpose:</b> Enhanced variant of the <codeph>nvl()</codeph> function. Tests an expression
- and returns different result values depending on whether it is <codeph>NULL</codeph> or not.
- If the first argument is <codeph>NULL</codeph>, returns the second argument.
- If the first argument is not <codeph>NULL</codeph>, returns the third argument.
- Equivalent to the <codeph>nvl2()</codeph> function from Oracle Database.
+ <b>Purpose:</b> Enhanced variant of the <codeph>NVL()</codeph> function. Tests an
+ expression and returns different result values depending on whether it is
+ <codeph>NULL</codeph> or not. If the first argument is <codeph>NULL</codeph>, returns
+ the second argument. If the first argument is not <codeph>NULL</codeph>, returns the
+ third argument. Equivalent to the <codeph>NVL2()</codeph> function from Oracle
+ Database.
<p>
<b>Return type:</b> Same as the first argument value
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_290"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show how a query can use special indicator values
- to represent null and not-null expression values. The first example tests
- an <codeph>INT</codeph> column and so uses special integer values.
- The second example tests a <codeph>STRING</codeph> column and so uses
- special string values.
+ The following examples show how a query can use special indicator values to
+ represent null and not-null expression values. The first example tests an
+ <codeph>INT</codeph> column and so uses special integer values. The second example
+ tests a <codeph>STRING</codeph> column and so uses special string values.
</p>
<codeblock>
select x, nvl2(x, 999, 0) from nvl2_demo;
@@ -499,22 +637,29 @@ select s, nvl2(s, 'is not null', 'is null') from nvl2_demo;
<dlentry rev="1.3.0" id="zeroifnull">
<dt>
- <codeph>zeroifnull(<varname>numeric_expr</varname>)</codeph>
+ ZEROIFNULL(type numeric_expr)
</dt>
- <dd><b>Purpose:</b> Returns 0 if the numeric expression evaluates to
- <codeph>NULL</codeph>, otherwise returns the result of the
- expression. <p>
- <b>Usage notes:</b> Used to avoid unexpected results due to
- unexpected propagation of <codeph>NULL</codeph> values in numeric
- calculations. Serves as shorthand for a more elaborate
- <codeph>CASE</codeph> expression, to simplify porting SQL with
- vendor extensions to Impala. </p>
- <p><b>Return type:</b> Same type as the input argument </p>
+ <dd>
+ <b>Purpose:</b> Returns 0 if the numeric expression evaluates to
+ <codeph>NULL</codeph>, otherwise returns the result of the expression.
+ <p>
+ <b>Usage notes:</b> Used to avoid unexpected results due to unexpected propagation
+ of <codeph>NULL</codeph> values in numeric calculations. Serves as shorthand for a
+ more elaborate <codeph>CASE</codeph> expression, to simplify porting SQL with vendor
+ extensions to Impala.
+ </p>
+
+ <p>
+ <b>Return type:</b> Same type as the input argument
+ </p>
+
<p conref="../shared/impala_common.xml#common/added_in_130"/>
</dd>
</dlentry>
</dl>
+
</conbody>
+
</concept>
[06/10] impala git commit: [DOCS] Built-in Functions doc format
Changes
Posted by mi...@apache.org.
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_conversion_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_conversion_functions.xml b/docs/topics/impala_conversion_functions.xml
index 4d38790..120a5fa 100644
--- a/docs/topics/impala_conversion_functions.xml
+++ b/docs/topics/impala_conversion_functions.xml
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?><!--
+<?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
@@ -20,7 +21,13 @@ under the License.
<concept id="conversion_functions">
<title>Impala Type Conversion Functions</title>
- <titlealts audience="PDF"><navtitle>Type Conversion Functions</navtitle></titlealts>
+
+ <titlealts audience="PDF">
+
+ <navtitle>Type Conversion Functions</navtitle>
+
+ </titlealts>
+
<prolog>
<metadata>
<data name="Category" value="Impala"/>
@@ -36,19 +43,20 @@ under the License.
<conbody>
<p>
- Conversion functions are usually used in combination with other functions, to explicitly pass the expected
- data types. Impala has strict rules regarding data types for function parameters. For example, Impala does
- not automatically convert a <codeph>DOUBLE</codeph> value to <codeph>FLOAT</codeph>, a
- <codeph>BIGINT</codeph> value to <codeph>INT</codeph>, or other conversion where precision could be lost or
- overflow could occur. Also, for reporting or dealing with loosely defined schemas in big data contexts,
- you might frequently need to convert values to or from the <codeph>STRING</codeph> type.
+ Conversion functions are usually used in combination with other functions, to explicitly
+ pass the expected data types. Impala has strict rules regarding data types for function
+ parameters. For example, Impala does not automatically convert a <codeph>DOUBLE</codeph>
+ value to <codeph>FLOAT</codeph>, a <codeph>BIGINT</codeph> value to <codeph>INT</codeph>,
+ or other conversion where precision could be lost or overflow could occur. Also, for
+ reporting or dealing with loosely defined schemas in big data contexts, you might
+ frequently need to convert values to or from the <codeph>STRING</codeph> type.
</p>
<note>
- Although in <keyword keyref="impala23_full"/>, the <codeph>SHOW FUNCTIONS</codeph> output for
- database <codeph>_IMPALA_BUILTINS</codeph> contains some function signatures
- matching the pattern <codeph>castto*</codeph>, these functions are not intended
- for public use and are expected to be hidden in future.
+ Although in <keyword keyref="impala23_full"/>, the <codeph>SHOW FUNCTIONS</codeph> output
+ for database <codeph>_IMPALA_BUILTINS</codeph> contains some function signatures matching
+ the pattern <codeph>castto*</codeph>, these functions are not intended for public use and
+ are expected to be hidden in future.
</note>
<p>
@@ -59,718 +67,138 @@ under the License.
Impala supports the following type conversion functions:
</p>
-<dl>
-
-<dlentry id="cast">
-<dt>
-<codeph>cast(<varname>expr</varname> AS <varname>type</varname>)</codeph>
-</dt>
-
-<dd>
-<indexterm audience="hidden">cast() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to any other type.
-If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Usage notes:</b>
-Use <codeph>CAST</codeph> when passing a column value or literal to a function that
-expects a parameter with a different type.
-Frequently used in SQL operations such as <codeph>CREATE TABLE AS SELECT</codeph>
-and <codeph>INSERT ... VALUES</codeph> to ensure that values from various sources
-are of the appropriate type for the destination columns.
-Where practical, do a one-time <codeph>CAST()</codeph> operation during the ingestion process
-to make each column into the appropriate type, rather than using many <codeph>CAST()</codeph>
-operations in each query; doing type conversions for each row during each query can be expensive
-for tables with millions or billions of rows.
-</p>
- <p conref="../shared/impala_common.xml#common/timezone_conversion_caveat"/>
-
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<codeblock>select concat('Here are the first ',10,' results.'); -- Fails
-select concat('Here are the first ',cast(10 as string),' results.'); -- Succeeds
-</codeblock>
-<p>
-The following example starts with a text table where every column has a type of <codeph>STRING</codeph>,
-which might be how you ingest data of unknown schema until you can verify the cleanliness of the underly values.
-Then it uses <codeph>CAST()</codeph> to create a new Parquet table with the same data, but using specific
-numeric data types for the columns with numeric data. Using numeric types of appropriate sizes can result in
-substantial space savings on disk and in memory, and performance improvements in queries,
-over using strings or larger-than-necessary numeric types.
-</p>
-<codeblock>create table t1 (name string, x string, y string, z string);
-
-create table t2 stored as parquet
-as select
+ <ul>
+ <li>
+ <xref href="#conversion_functions/cast">CAST</xref>
+ </li>
+
+ <li>
+ <xref href="#conversion_functions/typeof">TYPEOF</xref>
+ </li>
+ </ul>
+
+ <dl>
+ <dlentry id="cast">
+
+ <dt>
+ CAST(expr AS type)
+ </dt>
+
+ <dd>
+ <b>Purpose:</b> Converts the value of an expression to any other type. If the
+ expression value is of a type that cannot be converted to the target type, the result
+ is <codeph>NULL</codeph>.
+ <p>
+ <b>Usage notes:</b> Use <codeph>CAST</codeph> when passing a column value or literal
+ to a function that expects a parameter with a different type. Frequently used in SQL
+ operations such as <codeph>CREATE TABLE AS SELECT</codeph> and <codeph>INSERT ...
+ VALUES</codeph> to ensure that values from various sources are of the appropriate
+ type for the destination columns. Where practical, do a one-time
+ <codeph>CAST()</codeph> operation during the ingestion process to make each column
+ into the appropriate type, rather than using many <codeph>CAST()</codeph> operations
+ in each query; doing type conversions for each row during each query can be
+ expensive for tables with millions or billions of rows.
+ </p>
+
+ <p
+ conref="../shared/impala_common.xml#common/timezone_conversion_caveat"/>
+
+ <p conref="../shared/impala_common.xml#common/example_blurb"/>
+<codeblock>SELECT CONCAT('Here are the first ',10,' results.'); -- Fails
+SELECT CONCAT('Here are the first ',CAST(10 AS STRING),' results.'); -- Succeeds
+</codeblock>
+ <p>
+ The following example starts with a text table where every column has a type of
+ <codeph>STRING</codeph>, which might be how you ingest data of unknown schema until
+ you can verify the cleanliness of the underlying values. Then it uses
+ <codeph>CAST()</codeph> to create a new Parquet table with the same data, but using
+ specific numeric data types for the columns with numeric data. Using numeric types
+ of appropriate sizes can result in substantial space savings on disk and in memory,
+ and performance improvements in queries, over using strings or larger-than-necessary
+ numeric types.
+ </p>
+<codeblock>CREATE TABLE t1 (name STRING, x STRING, y STRING, z STRING);
+
+CREATE TABLE t2 STORED AS PARQUET
+AS SELECT
name,
- cast(x as bigint) x,
- cast(y as timestamp) y,
- cast(z as smallint) z
-from t1;
-
-describe t2;
-+------+----------+---------+
-| name | type | comment |
-+------+----------+---------+
-| name | string | |
-| x | bigint | |
-| y | smallint | |
-| z | tinyint | |
-+------+----------+---------+
-</codeblock>
-<p conref="../shared/impala_common.xml#common/related_info"/>
-<p>
-<!-- TK: Can you cast to or from MAP, ARRAY, STRUCT? -->
- For details of casts from each kind of data type, see the description of
- the appropriate type:
- <xref href="impala_tinyint.xml#tinyint"/>,
- <xref href="impala_smallint.xml#smallint"/>,
- <xref href="impala_int.xml#int"/>,
- <xref href="impala_bigint.xml#bigint"/>,
- <xref href="impala_float.xml#float"/>,
- <xref href="impala_double.xml#double"/>,
- <xref href="impala_decimal.xml#decimal"/>,
- <xref href="impala_string.xml#string"/>,
- <xref href="impala_char.xml#char"/>,
- <xref href="impala_varchar.xml#varchar"/>,
- <xref href="impala_timestamp.xml#timestamp"/>,
- <xref href="impala_boolean.xml#boolean"/>
-</p>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttobigint" audience="hidden">
-<dt>
-<codeph>casttobigint(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttobigint() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>BIGINT</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>bigint</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>create table small_types (x tinyint, y smallint, z int);
-
-create table big_types as
- select casttobigint(x) as x, casttobigint(y) as y, casttobigint(z) as z
- from small_types;
-
-describe big_types;
-+------+--------+---------+
-| name | type | comment |
-+------+--------+---------+
-| x | bigint | |
-| y | bigint | |
-| z | bigint | |
-+------+--------+---------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttoboolean" audience="hidden">
-<dt>
-<codeph>casttoboolean(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttoboolean() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>BOOLEAN</codeph>.
-Numeric values of 0 evaluate to <codeph>false</codeph>, and non-zero values evaluate to <codeph>true</codeph>.
-If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-In particular, <codeph>STRING</codeph> values (even <codeph>'1'</codeph>, <codeph>'0'</codeph>, <codeph>'true'</codeph>
-or <codeph>'false'</codeph>) always return <codeph>NULL</codeph> when converted to <codeph>BOOLEAN</codeph>.
-<p><b>Return type:</b> <codeph>boolean</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>select casttoboolean(0);
-+------------------+
-| casttoboolean(0) |
-+------------------+
-| false |
-+------------------+
-
-select casttoboolean(1);
-+------------------+
-| casttoboolean(1) |
-+------------------+
-| true |
-+------------------+
-
-select casttoboolean(99);
-+-------------------+
-| casttoboolean(99) |
-+-------------------+
-| true |
-+-------------------+
-
-select casttoboolean(0.0);
-+--------------------+
-| casttoboolean(0.0) |
-+--------------------+
-| false |
-+--------------------+
-
-select casttoboolean(0.5);
-+--------------------+
-| casttoboolean(0.5) |
-+--------------------+
-| true |
-+--------------------+
-
-select casttoboolean('');
-+-------------------+
-| casttoboolean('') |
-+-------------------+
-| NULL |
-+-------------------+
-
-select casttoboolean('yes');
-+----------------------+
-| casttoboolean('yes') |
-+----------------------+
-| NULL |
-+----------------------+
-
-select casttoboolean('0');
-+--------------------+
-| casttoboolean('0') |
-+--------------------+
-| NULL |
-+--------------------+
-
-select casttoboolean('true');
-+-----------------------+
-| casttoboolean('true') |
-+-----------------------+
-| NULL |
-+-----------------------+
-
-select casttoboolean('false');
-+------------------------+
-| casttoboolean('false') |
-+------------------------+
-| NULL |
-+------------------------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttochar" audience="hidden">
-<dt>
-<codeph>casttochar(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttochar() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>CHAR</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>char</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>create table char_types as select casttochar('hello world') as c1, casttochar('xyz') as c2, casttochar('x') as c3;
-+-------------------+
-| summary |
-+-------------------+
-| Inserted 1 row(s) |
-+-------------------+
-
-describe char_types;
-+------+--------+---------+
-| name | type | comment |
-+------+--------+---------+
-| c1 | string | |
-| c2 | string | |
-| c3 | string | |
-+------+--------+---------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttodecimal" audience="hidden">
-<dt>
-<codeph>casttodecimal(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttodecimal() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>DECIMAL</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>decimal</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>select casttodecimal(5.4);
-+--------------------+
-| casttodecimal(5.4) |
-+--------------------+
-| 5.4 |
-+--------------------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttodouble" audience="hidden">
-<dt>
-<codeph>casttodouble(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttodouble() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>DOUBLE</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>double</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>select casttodouble(5);
-+-----------------+
-| casttodouble(5) |
-+-----------------+
-| 5 |
-+-----------------+
-
-select casttodouble('3.141');
-+-----------------------+
-| casttodouble('3.141') |
-+-----------------------+
-| 3.141 |
-+-----------------------+
-
-select casttodouble(1e6);
-+--------------------+
-| casttodouble(1e+6) |
-+--------------------+
-| 1000000 |
-+--------------------+
-
-select casttodouble(true);
-+--------------------+
-| casttodouble(true) |
-+--------------------+
-| 1 |
-+--------------------+
-
-select casttodouble(now());
-+---------------------+
-| casttodouble(now()) |
-+---------------------+
-| 1447622306.031178 |
-+---------------------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttofloat" audience="hidden">
-<dt>
-<codeph>casttofloat(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttofloat() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>FLOAT</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>float</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>select casttofloat(5);
-+----------------+
-| casttofloat(5) |
-+----------------+
-| 5 |
-+----------------+
-
-select casttofloat('3.141');
-+----------------------+
-| casttofloat('3.141') |
-+----------------------+
-| 3.141000032424927 |
-+----------------------+
-
-select casttofloat(1e6);
-+-------------------+
-| casttofloat(1e+6) |
-+-------------------+
-| 1000000 |
-+-------------------+
-
-select casttofloat(true);
-+-------------------+
-| casttofloat(true) |
-+-------------------+
-| 1 |
-+-------------------+
-
-select casttofloat(now());
-+--------------------+
-| casttofloat(now()) |
-+--------------------+
-| 1447622400 |
-+--------------------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttoint" audience="hidden">
-<dt>
-<codeph>casttoint(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttoint() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>INT</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>int</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>select casttoint(5.4);
-+----------------+
-| casttoint(5.4) |
-+----------------+
-| 5 |
-+----------------+
-
-select casttoint(true);
-+-----------------+
-| casttoint(true) |
-+-----------------+
-| 1 |
-+-----------------+
-
-select casttoint(now());
-+------------------+
-| casttoint(now()) |
-+------------------+
-| 1447622487 |
-+------------------+
-
-select casttoint('3.141');
-+--------------------+
-| casttoint('3.141') |
-+--------------------+
-| NULL |
-+--------------------+
-
-select casttoint('3');
-+----------------+
-| casttoint('3') |
-+----------------+
-| 3 |
-+----------------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttosmallint" audience="hidden">
-<dt>
-<codeph>casttosmallint(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttosmallint() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>SMALLINT</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>smallint</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>create table big_types (x bigint, y int, z smallint);
-
-create table small_types as
- select casttosmallint(x) as x, casttosmallint(y) as y, casttosmallint(z) as z
- from big_types;
-
-describe small_types;
-+------+----------+---------+
-| name | type | comment |
-+------+----------+---------+
-| x | smallint | |
-| y | smallint | |
-| z | smallint | |
-+------+----------+---------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttostring" audience="hidden">
-<dt>
-<codeph>casttostring(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttostring() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>STRING</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>string</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>create table numeric_types (x int, y bigint, z tinyint);
-
-create table string_types as
- select casttostring(x) as x, casttostring(y) as y, casttostring(z) as z
- from numeric_types;
-
-describe string_types;
-+------+--------+---------+
-| name | type | comment |
-+------+--------+---------+
-| x | string | |
-| y | string | |
-| z | string | |
-+------+--------+---------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttotimestamp" audience="hidden">
-<dt>
-<codeph>casttotimestamp(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttotimestamp() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>TIMESTAMP</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>timestamp</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>select casttotimestamp(1000);
-+-----------------------+
-| casttotimestamp(1000) |
-+-----------------------+
-| 1970-01-01 00:16:40 |
-+-----------------------+
-
-select casttotimestamp(1000.0);
-+-------------------------+
-| casttotimestamp(1000.0) |
-+-------------------------+
-| 1970-01-01 00:16:40 |
-+-------------------------+
-
-select casttotimestamp('1000');
-+-------------------------+
-| casttotimestamp('1000') |
-+-------------------------+
-| NULL |
-+-------------------------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttotinyint" audience="hidden">
-<dt>
-<codeph>casttotinyint(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttotinyint() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>TINYINT</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>tinyint</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>create table big_types (x bigint, y int, z smallint);
-
-create table tiny_types as
- select casttotinyint(x) as x, casttotinyint(y) as y, casttotinyint(z) as z
- from big_types;
-
-describe tiny_types;
-+------+---------+---------+
-| name | type | comment |
-+------+---------+---------+
-| x | tinyint | |
-| y | tinyint | |
-| z | tinyint | |
-+------+---------+---------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="casttovarchar" audience="hidden">
-<dt>
-<codeph>casttovarchar(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">casttovarchar() function</indexterm>
-<b>Purpose:</b> Converts the value of an expression to <codeph>VARCHAR</codeph>. If the expression value is of a type that cannot be converted to the target type, the result is <codeph>NULL</codeph>.
-<p><b>Return type:</b> <codeph>varchar</codeph></p>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_usage"/>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p conref="../shared/impala_common.xml#common/cast_convenience_fn_example"/>
-<codeblock>select casttovarchar('abcd');
-+-----------------------+
-| casttovarchar('abcd') |
-+-----------------------+
-| abcd |
-+-----------------------+
-
-select casttovarchar(999);
-+--------------------+
-| casttovarchar(999) |
-+--------------------+
-| 999 |
-+--------------------+
-
-select casttovarchar(999.5);
-+----------------------+
-| casttovarchar(999.5) |
-+----------------------+
-| 999.5 |
-+----------------------+
-
-select casttovarchar(now());
-+-------------------------------+
-| casttovarchar(now()) |
-+-------------------------------+
-| 2015-11-15 21:26:13.528073000 |
-+-------------------------------+
-
-select casttovarchar(true);
-+---------------------+
-| casttovarchar(true) |
-+---------------------+
-| 1 |
-+---------------------+
-</codeblock>
-</dd>
-</dlentry>
-
-<dlentry rev="2.3.0" id="typeof">
-<dt>
-<codeph>typeof(type value)</codeph>
-</dt>
-<dd>
-<indexterm audience="hidden">typeof() function</indexterm>
-<b>Purpose:</b> Returns the name of the data type corresponding to an expression. For types with
-extra attributes, such as length for <codeph>CHAR</codeph> and <codeph>VARCHAR</codeph>,
-or precision and scale for <codeph>DECIMAL</codeph>, includes the full specification of the type.
+ CAST(x AS BIGINT) x,
+ CAST(y AS TIMESTAMP) y,
+ CAST(z AS SMALLINT) z
+FROM t1;</codeblock>
+ <p conref="../shared/impala_common.xml#common/related_info"/>
+
+ <p>
+ For details of casts from each kind of data type, see the description of the
+ appropriate type: <xref
+ href="impala_tinyint.xml#tinyint"/>,
+ <xref
+ href="impala_smallint.xml#smallint"/>,
+ <xref
+ href="impala_int.xml#int"/>,
+ <xref href="impala_bigint.xml#bigint"
+ />,
+ <xref href="impala_float.xml#float"/>,
+ <xref
+ href="impala_double.xml#double"/>,
+ <xref
+ href="impala_decimal.xml#decimal"/>,
+ <xref
+ href="impala_string.xml#string"/>,
+ <xref
+ href="impala_char.xml#char"/>,
+ <xref
+ href="impala_varchar.xml#varchar"/>,
+ <xref
+ href="impala_timestamp.xml#timestamp"/>,
+ <xref
+ href="impala_boolean.xml#boolean"/>
+ </p>
+ </dd>
+
+ </dlentry>
+
+ <dlentry rev="2.3.0" id="typeof">
+
+ <dt>
+ TYPEOF(type value)
+ </dt>
+
+ <dd>
+ <b>Purpose:</b> Returns the name of the data type corresponding to an expression. For
+ types with extra attributes, such as length for <codeph>CHAR</codeph> and
+ <codeph>VARCHAR</codeph>, or precision and scale for <codeph>DECIMAL</codeph>,
+ includes the full specification of the type.
<!-- To do: How about for columns of complex types? Or fields within complex types? -->
-<p><b>Return type:</b> <codeph>string</codeph></p>
-<p><b>Usage notes:</b> Typically used in interactive exploration of a schema, or in application code that programmatically generates schema definitions such as <codeph>CREATE TABLE</codeph> statements.
-For example, previously, to understand the type of an expression such as
-<codeph>col1 / col2</codeph> or <codeph>concat(col1, col2, col3)</codeph>,
-you might have created a dummy table with a single row, using syntax such as <codeph>CREATE TABLE foo AS SELECT 5 / 3.0</codeph>,
-and then doing a <codeph>DESCRIBE</codeph> to see the type of the row.
-Or you might have done a <codeph>CREATE TABLE AS SELECT</codeph> operation to create a table and
-copy data into it, only learning the types of the columns by doing a <codeph>DESCRIBE</codeph> afterward.
-This technique is especially useful for arithmetic expressions involving <codeph>DECIMAL</codeph> types,
-because the precision and scale of the result is typically different than that of the operands.
-</p>
-<p conref="../shared/impala_common.xml#common/added_in_230"/>
-<p conref="../shared/impala_common.xml#common/example_blurb"/>
-<p>
-These examples show how to check the type of a simple literal or function value.
-Notice how adding even tiny integers together changes the data type of the result to
-avoid overflow, and how the results of arithmetic operations on <codeph>DECIMAL</codeph> values
-have specific precision and scale attributes.
-</p>
-<codeblock>select typeof(2)
-+-----------+
-| typeof(2) |
-+-----------+
-| TINYINT |
-+-----------+
-
-select typeof(2+2)
-+---------------+
-| typeof(2 + 2) |
-+---------------+
-| SMALLINT |
-+---------------+
-
-select typeof('xyz')
-+---------------+
-| typeof('xyz') |
-+---------------+
-| STRING |
-+---------------+
-
-select typeof(now())
-+---------------+
-| typeof(now()) |
-+---------------+
-| TIMESTAMP |
-+---------------+
-
-select typeof(5.3 / 2.1)
-+-------------------+
-| typeof(5.3 / 2.1) |
-+-------------------+
-| DECIMAL(6,4) |
-+-------------------+
-
-select typeof(5.30001 / 2342.1);
-+--------------------------+
-| typeof(5.30001 / 2342.1) |
-+--------------------------+
-| DECIMAL(13,11) |
-+--------------------------+
-
-select typeof(typeof(2+2))
-+-----------------------+
-| typeof(typeof(2 + 2)) |
-+-----------------------+
-| STRING |
-+-----------------------+
-</codeblock>
-
-<p>
-This example shows how even if you do not have a record of the type of a column,
-for example because the type was changed by <codeph>ALTER TABLE</codeph> after the
-original <codeph>CREATE TABLE</codeph>, you can still find out the type in a
-more compact form than examining the full <codeph>DESCRIBE</codeph> output.
-Remember to use <codeph>LIMIT 1</codeph> in such cases, to avoid an identical
-result value for every row in the table.
-</p>
-<codeblock>create table typeof_example (a int, b tinyint, c smallint, d bigint);
-
-/* Empty result set if there is no data in the table. */
-select typeof(a) from typeof_example;
-
-/* OK, now we have some data but the type of column A is being changed. */
-insert into typeof_example values (1, 2, 3, 4);
-alter table typeof_example change a a bigint;
-
-/* We can always find out the current type of that column without doing a full DESCRIBE. */
-select typeof(a) from typeof_example limit 1;
-+-----------+
-| typeof(a) |
-+-----------+
-| BIGINT |
-+-----------+
-</codeblock>
-<p>
-This example shows how you might programmatically generate a <codeph>CREATE TABLE</codeph> statement
-with the appropriate column definitions to hold the result values of arbitrary expressions.
-The <codeph>typeof()</codeph> function lets you construct a detailed <codeph>CREATE TABLE</codeph> statement
-without actually creating the table, as opposed to <codeph>CREATE TABLE AS SELECT</codeph> operations
-where you create the destination table but only learn the column data types afterward through <codeph>DESCRIBE</codeph>.
-</p>
-<codeblock>describe typeof_example;
-+------+----------+---------+
-| name | type | comment |
-+------+----------+---------+
-| a | bigint | |
-| b | tinyint | |
-| c | smallint | |
-| d | bigint | |
-+------+----------+---------+
-
-/* An ETL or business intelligence tool might create variations on a table with different file formats,
- different sets of columns, and so on. TYPEOF() lets an application introspect the types of the original columns. */
-select concat('create table derived_table (a ', typeof(a), ', b ', typeof(b), ', c ',
- typeof(c), ', d ', typeof(d), ') stored as parquet;')
- as 'create table statement'
-from typeof_example limit 1;
-+-------------------------------------------------------------------------------------------+
-| create table statement |
-+-------------------------------------------------------------------------------------------+
-| create table derived_table (a BIGINT, b TINYINT, c SMALLINT, d BIGINT) stored as parquet; |
-+-------------------------------------------------------------------------------------------+
-</codeblock>
-</dd>
-</dlentry>
-
-</dl>
+ <p>
+ <b>Return type:</b> <codeph>STRING</codeph>
+ </p>
+
+ <p>
+ <b>Usage notes:</b> Typically used in interactive exploration of a schema, or in
+ application code that programmatically generates schema definitions such as
+ <codeph>CREATE TABLE</codeph> statements, for example, to get the type of an
+ expression such as <codeph>col1 / col2</codeph> or <codeph>CONCAT(col1, col2,
+ col3)</codeph>. This function is especially useful for arithmetic expressions
+ involving <codeph>DECIMAL</codeph> types because the precision and scale of the
+ result is can be different than that of the operands.
+ </p>
+
+ <p conref="../shared/impala_common.xml#common/added_in_230"/>
+
+ <p conref="../shared/impala_common.xml#common/example_blurb"/>
+<codeblock>SELECT TYPEOF(2), TYPEOF(2+2);
++-----------+---------------+
+| typeof(2) | typeof(2 + 2) |
++-----------+---------------+
+| TINYINT | SMALLINT |
++-----------+---------------+
+</codeblock>
+ </dd>
+
+ </dlentry>
+ </dl>
</conbody>
+
</concept>
[09/10] impala git commit: IMPALA-7688: Fix spurious error messages
when updating owner privileges
Posted by mi...@apache.org.
IMPALA-7688: Fix spurious error messages when updating owner privileges
Failure in updating owner privileges is not an issue since this could
mean a Sentry refresh occurred while updating owner privileges and
Sentry refresh itself will update all privileges including owner
privileges. This patch changes the code to log the failure in
updating owner privileges as WARN instead of ERROR.
Testing:
- Ran all FE tests
- Ran all E2E authorization tests
Change-Id: I4b46df01c5675ffed6528b7a73e68518664d8be0
Reviewed-on: http://gerrit.cloudera.org:8080/11649
Reviewed-by: Impala Public Jenkins <im...@cloudera.com>
Tested-by: Impala Public Jenkins <im...@cloudera.com>
Project: http://git-wip-us.apache.org/repos/asf/impala/repo
Commit: http://git-wip-us.apache.org/repos/asf/impala/commit/0cbe37af
Tree: http://git-wip-us.apache.org/repos/asf/impala/tree/0cbe37af
Diff: http://git-wip-us.apache.org/repos/asf/impala/diff/0cbe37af
Branch: refs/heads/master
Commit: 0cbe37afc8f77fd8e0aef7e710e2d1b214c1c5b1
Parents: 6099255
Author: Fredy Wijaya <fw...@cloudera.com>
Authored: Mon Oct 8 22:34:43 2018 -0700
Committer: Impala Public Jenkins <im...@cloudera.com>
Committed: Thu Oct 11 08:44:02 2018 +0000
----------------------------------------------------------------------
.../impala/service/CatalogOpExecutor.java | 41 +++++++++++++++-----
1 file changed, 31 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/impala/blob/0cbe37af/fe/src/main/java/org/apache/impala/service/CatalogOpExecutor.java
----------------------------------------------------------------------
diff --git a/fe/src/main/java/org/apache/impala/service/CatalogOpExecutor.java b/fe/src/main/java/org/apache/impala/service/CatalogOpExecutor.java
index 36725df..aeb23df 100644
--- a/fe/src/main/java/org/apache/impala/service/CatalogOpExecutor.java
+++ b/fe/src/main/java/org/apache/impala/service/CatalogOpExecutor.java
@@ -1028,8 +1028,8 @@ public class CatalogOpExecutor {
* operations.
*/
private void updateOwnerPrivileges(String databaseName, String tableName,
- String serverName, String oldOwner, PrincipalType oldOwnerType, String newOwner,
- PrincipalType newOwnerType, TDdlExecResponse resp) {
+ String serverName, String oldOwner, PrincipalType oldOwnerType, String newOwner,
+ PrincipalType newOwnerType, TDdlExecResponse resp) {
if (catalog_.getSentryProxy() == null || !catalog_.getSentryProxy()
.isObjectOwnershipEnabled()) return;
Preconditions.checkNotNull(serverName);
@@ -1039,10 +1039,10 @@ public class CatalogOpExecutor {
} else {
filter = createTableOwnerPrivilegeFilter(databaseName, tableName, serverName);
}
- if(oldOwner != null && !oldOwner.isEmpty()) {
+ if (oldOwner != null && !oldOwner.isEmpty()) {
removePrivilegeFromCatalog(oldOwner, oldOwnerType, filter, resp);
}
- if(newOwner != null && !newOwner.isEmpty()) {
+ if (newOwner != null && !newOwner.isEmpty()) {
addPrivilegeToCatalog(newOwner, newOwnerType, filter, resp);
}
}
@@ -2865,8 +2865,11 @@ public class CatalogOpExecutor {
*/
private void removePrivilegeFromCatalog(String ownerString, PrincipalType ownerType,
TPrivilege filter, TDdlExecResponse response) {
+ Preconditions.checkNotNull(ownerString);
+ Preconditions.checkNotNull(ownerType);
+ Preconditions.checkNotNull(filter);
try {
- PrincipalPrivilege removedPrivilege;
+ PrincipalPrivilege removedPrivilege = null;
switch (ownerType) {
case ROLE:
removedPrivilege = catalog_.removeRolePrivilege(ownerString,
@@ -2877,14 +2880,21 @@ public class CatalogOpExecutor {
PrincipalPrivilege.buildPrivilegeName(filter));
break;
default:
- throw new CatalogException("Unexpected ownerType: " + ownerType.name());
+ Preconditions.checkArgument(false,
+ "Unexpected PrincipalType: " + ownerType.name());
}
if (removedPrivilege != null) {
response.result.addToRemoved_catalog_objects(removedPrivilege
.toTCatalogObject());
}
} catch (CatalogException e) {
- LOG.error("Error removing privilege: ", e);
+ // Failure removing an owner privilege is not an issue because it could be
+ // that Sentry refresh occurred while executing this method and this method
+ // is used as a a best-effort to do what Sentry refresh does to make the
+ // owner privilege available right away without having to wait for a Sentry
+ // refresh.
+ LOG.warn("Unable to remove owner privilege: " +
+ PrincipalPrivilege.buildPrivilegeName(filter), e);
}
}
@@ -2894,9 +2904,12 @@ public class CatalogOpExecutor {
*/
private void addPrivilegeToCatalog(String ownerString, PrincipalType ownerType,
TPrivilege filter, TDdlExecResponse response) {
+ Preconditions.checkNotNull(ownerString);
+ Preconditions.checkNotNull(ownerType);
+ Preconditions.checkNotNull(filter);
try {
Principal owner;
- PrincipalPrivilege cPrivilege;
+ PrincipalPrivilege cPrivilege = null;
if (ownerType == PrincipalType.USER) {
Reference<Boolean> existingUser = new Reference<>();
owner = catalog_.addUserIfNotExists(ownerString, existingUser);
@@ -2908,15 +2921,23 @@ public class CatalogOpExecutor {
}
} else if (ownerType == PrincipalType.ROLE) {
owner = catalog_.getAuthPolicy().getRole(ownerString);
+ Preconditions.checkNotNull(owner);
filter.setPrincipal_id(owner.getId());
filter.setPrincipal_type(TPrincipalType.ROLE);
cPrivilege = catalog_.addRolePrivilege(ownerString, filter);
} else {
- throw new CatalogException("Unexpected PrincipalType: " + ownerType.name());
+ Preconditions.checkArgument(false, "Unexpected PrincipalType: " +
+ ownerType.name());
}
response.result.addToUpdated_catalog_objects(cPrivilege.toTCatalogObject());
} catch (CatalogException e) {
- LOG.error("Error adding privilege: ", e);
+ // Failure adding an owner privilege is not an issue because it could be
+ // that Sentry refresh occurred while executing this method and this method
+ // is used as a a best-effort to do what Sentry refresh does to make the
+ // owner privilege available right away without having to wait for a Sentry
+ // refresh.
+ LOG.warn("Unable to add owner privilege: " +
+ PrincipalPrivilege.buildPrivilegeName(filter), e);
}
}
[04/10] impala git commit: [DOCS] Built-in Functions doc format
Changes
Posted by mi...@apache.org.
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_functions.xml b/docs/topics/impala_functions.xml
index fe26d31..724253b 100644
--- a/docs/topics/impala_functions.xml
+++ b/docs/topics/impala_functions.xml
@@ -73,7 +73,7 @@ under the License.
</li>
<li>
- <xref href="impala_aggregate_functions.xml#aggregate_functions"/>.
+ <xref href="impala_aggregate_functions.xml#aggregate_functions"/>
</li>
<li>
[02/10] impala git commit: [DOCS] Built-in Functions doc format
Changes
Posted by mi...@apache.org.
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_misc_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_misc_functions.xml b/docs/topics/impala_misc_functions.xml
index 1b5bfd4..b2cfa62 100644
--- a/docs/topics/impala_misc_functions.xml
+++ b/docs/topics/impala_misc_functions.xml
@@ -21,7 +21,13 @@ under the License.
<concept id="misc_functions">
<title>Impala Miscellaneous Functions</title>
- <titlealts audience="PDF"><navtitle>Miscellaneous Functions</navtitle></titlealts>
+
+ <titlealts audience="PDF">
+
+ <navtitle>Miscellaneous Functions</navtitle>
+
+ </titlealts>
+
<prolog>
<metadata>
<data name="Category" value="Impala"/>
@@ -36,23 +42,58 @@ under the License.
<conbody>
<p>
- Impala supports the following utility functions that do not operate on a particular column or data type:
+ Impala supports the following utility functions that do not operate on a particular column
+ or data type:
</p>
+ <ul>
+ <li>
+ <xref href="#misc_functions/current_database">CURRENT_DATABASE</xref>
+ </li>
+
+ <li>
+ <xref href="#misc_functions/effective_user">EFFECTIVE_USER</xref>
+ </li>
+
+ <li>
+ <xref href="#misc_functions/pid">PID</xref>
+ </li>
+
+ <li>
+ <xref href="#misc_functions/sleep">SLEEP</xref>
+ </li>
+
+ <li>
+ <xref href="#misc_functions/user">USER</xref>
+ </li>
+
+ <li>
+ <xref href="#misc_functions/uuid">UUID</xref>
+ </li>
+
+ <li>
+ <xref href="#misc_functions/version">VERSION</xref>
+ </li>
+
+ <li>
+ <xref href="#misc_functions/coordinator">COORDINATOR</xref>
+ </li>
+ </ul>
+
<dl>
<dlentry rev="1.3.0" id="current_database">
<dt>
- <codeph>current_database()</codeph>
+ CURRENT_DATABASE()
</dt>
<dd>
- <indexterm audience="hidden">current_database() function</indexterm>
- <b>Purpose:</b> Returns the database that the session is currently using, either <codeph>default</codeph>
- if no database has been selected, or whatever database the session switched to through a
- <codeph>USE</codeph> statement or the <cmdname>impalad</cmdname><codeph>-d</codeph> option.
+ <b>Purpose:</b> Returns the database that the session is currently using, either
+ <codeph>default</codeph> if no database has been selected, or whatever database the
+ session switched to through a <codeph>USE</codeph> statement or the
+ <cmdname>impalad</cmdname> <codeph>-d</codeph> option.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -61,16 +102,16 @@ under the License.
<dlentry rev="5.4.5" id="effective_user">
<dt>
- <codeph>effective_user()</codeph>
+ EFFECTIVE_USER()
</dt>
<dd>
- <indexterm audience="hidden">effective_user() function</indexterm>
- <b>Purpose:</b> Typically returns the same value as <codeph>user()</codeph>,
- except if delegation is enabled, in which case it returns the ID of the delegated user.
+ <b>Purpose:</b> Typically returns the same value as <codeph>USER()</codeph>. If
+ delegation is enabled, it returns the ID of the delegated user.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p>
<b>Added in:</b> <keyword keyref="impala225"/>
</p>
@@ -81,37 +122,38 @@ under the License.
<dlentry rev="1.3.0" id="pid">
<dt>
- <codeph>pid()</codeph>
+ PID()
</dt>
<dd>
- <indexterm audience="hidden">pid() function</indexterm>
- <b>Purpose:</b> Returns the process ID of the <cmdname>impalad</cmdname> daemon that the session is
- connected to. You can use it during low-level debugging, to issue Linux commands that trace, show the
- arguments, and so on the <cmdname>impalad</cmdname> process.
+ <b>Purpose:</b> Returns the process ID of the <cmdname>impalad</cmdname> daemon that
+ the session is connected to. You can use it during low-level debugging, to issue Linux
+ commands that trace, show the arguments, and so on the <cmdname>impalad</cmdname>
+ process.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
</dd>
</dlentry>
- <dlentry audience="hidden" id="sleep">
+ <dlentry id="sleep">
<dt>
- <codeph>sleep(int ms)</codeph>
+ SLEEP(INT ms)
</dt>
<dd>
- <indexterm audience="hidden">sleep() function</indexterm>
- <b>Purpose:</b> Pauses the query for a specified number of milliseconds. For slowing down queries with
- small result sets enough to monitor runtime execution, memory usage, or other factors that otherwise
- would be difficult to capture during the brief interval of query execution. When used in the
- <codeph>SELECT</codeph> list, it is called once for each row in the result set; adjust the number of
- milliseconds accordingly. For example, a query <codeph>SELECT *, sleep(5) FROM
- table_with_1000_rows</codeph> would take at least 5 seconds to complete (5 milliseconds * 1000 rows in
- result set). To avoid an excessive number of concurrent queries, use this function for troubleshooting on
- test and development systems, not for production queries.
+ <b>Purpose:</b> Pauses the query for a specified number of milliseconds. For slowing
+ down queries with small result sets enough to monitor runtime execution, memory usage,
+ or other factors that otherwise would be difficult to capture during the brief
+ interval of query execution. When used in the <codeph>SELECT</codeph> list, it is
+ called once for each row in the result set; adjust the number of milliseconds
+ accordingly. For example, a query <codeph>SELECT *, SLEEP(5) FROM
+ table_with_1000_rows</codeph> would take at least 5 seconds to complete (5
+ milliseconds * 1000 rows in result set). To avoid an excessive number of concurrent
+ queries, use this function for troubleshooting on test and development systems, not
+ for production queries.
<p>
<b>Return type:</b> N/A
</p>
@@ -122,22 +164,25 @@ under the License.
<dlentry rev="1.1" id="user">
<dt>
- <codeph>user()</codeph>
+ USER()
</dt>
<dd>
- <indexterm audience="hidden">user() function</indexterm>
- <b>Purpose:</b> Returns the username of the Linux user who is connected to the <cmdname>impalad</cmdname>
- daemon. Typically called a single time, in a query without any <codeph>FROM</codeph> clause, to
- understand how authorization settings apply in a security context; once you know the logged-in username,
- you can check which groups that user belongs to, and from the list of groups you can check which roles
- are available to those groups through the authorization policy file.
+ <b>Purpose:</b> Returns the username of the Linux user who is connected to the
+ <cmdname>impalad</cmdname> daemon. Typically called a single time, in a query without
+ any <codeph>FROM</codeph> clause, to understand how authorization settings apply in a
+ security context; once you know the logged-in username, you can check which groups
+ that user belongs to, and from the list of groups you can check which roles are
+ available to those groups through the authorization policy file.
<p conref="../shared/impala_common.xml#common/user_kerberized"/>
+
<p>
- When delegation is enabled, consider calling the <codeph>effective_user()</codeph> function instead.
+ When delegation is enabled, consider calling the <codeph>EFFECTIVE_USER()</codeph>
+ function instead.
</p>
+
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -146,25 +191,33 @@ under the License.
<dlentry rev="2.5.0 IMPALA-1477" id="uuid">
<dt>
- <codeph>uuid()</codeph>
+ UUID()
</dt>
<dd>
- <indexterm audience="hidden">uuid() function</indexterm>
- <b>Purpose:</b> Returns a <xref href="https://en.wikipedia.org/wiki/Universally_unique_identifier" scope="external" format="html">universal unique identifier</xref>, a 128-bit value encoded as a string with groups of hexadecimal digits separated by dashes.
+ <b>Purpose:</b> Returns a
+ <xref
+ href="https://en.wikipedia.org/wiki/Universally_unique_identifier"
+ scope="external" format="html">universal
+ unique identifier</xref>, a 128-bit value encoded as a string with groups of
+ hexadecimal digits separated by dashes.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_250"/>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Ascending numeric sequences of type <codeph>BIGINT</codeph> are often used
- as identifiers within a table, and as join keys across multiple tables.
- The <codeph>uuid()</codeph> value is a convenient alternative that does not
- require storing or querying the highest sequence number. For example, you
- can use it to quickly construct new unique identifiers during a data import job,
- or to combine data from different tables without the likelihood of ID collisions.
+ Ascending numeric sequences of type <codeph>BIGINT</codeph> are often used as
+ identifiers within a table, and as join keys across multiple tables. The
+ <codeph>UUID()</codeph> value is a convenient alternative that does not require
+ storing or querying the highest sequence number. For example, you can use it to
+ quickly construct new unique identifiers during a data import job, or to combine
+ data from different tables without the likelihood of ID collisions.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>
-- Each call to uuid() produces a new arbitrary value.
@@ -194,41 +247,44 @@ select uuid() from four_row_table;
<dlentry id="version">
<dt>
- <codeph>version()</codeph>
+ VERSION()
</dt>
<dd>
- <indexterm audience="hidden">version() function</indexterm>
- <b>Purpose:</b> Returns information such as the precise version number and build date for the
- <codeph>impalad</codeph> daemon that you are currently connected to. Typically used to confirm that you
- are connected to the expected level of Impala to use a particular feature, or to connect to several nodes
- and confirm they are all running the same level of <cmdname>impalad</cmdname>.
+ <b>Purpose:</b> Returns information such as the precise version number and build date
+ for the <codeph>impalad</codeph> daemon that you are currently connected to. Typically
+ used to confirm that you are connected to the expected level of Impala to use a
+ particular feature, or to connect to several nodes and confirm they are all running
+ the same level of <cmdname>impalad</cmdname>.
<p>
- <b>Return type:</b> <codeph>string</codeph> (with one or more embedded newlines)
+ <b>Return type:</b> <codeph>STRING</codeph> (with one or more embedded newlines)
</p>
</dd>
</dlentry>
+ <dlentry id="coordinator" rev="IMPALA-589">
-
- <dlentry id="coordinator">
<dt>
- <codeph>coordinator()</codeph>
+ COORDINATOR()
</dt>
<dd>
- <indexterm audience="hidden">coordinator() function</indexterm>
<b>Purpose:</b> Returns the name of the host which is running the
- <codeph>impalad</codeph> daemon that is acting as the <codeph>coordinator</codeph>
- for the curent query.
+ <codeph>impalad</codeph> daemon that is acting as the <codeph>coordinator</codeph> for
+ the current query.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
+ </p>
+
+ <p>
+ <b>Added in:</b> <keyword keyref="impala31"/>
</p>
</dd>
</dlentry>
-
</dl>
+
</conbody>
+
</concept>
http://git-wip-us.apache.org/repos/asf/impala/blob/e8ee827a/docs/topics/impala_string_functions.xml
----------------------------------------------------------------------
diff --git a/docs/topics/impala_string_functions.xml b/docs/topics/impala_string_functions.xml
index ed5d028..a32dbf7 100644
--- a/docs/topics/impala_string_functions.xml
+++ b/docs/topics/impala_string_functions.xml
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?><!--
+<?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
@@ -20,7 +21,13 @@ under the License.
<concept id="string_functions">
<title>Impala String Functions</title>
- <titlealts audience="PDF"><navtitle>String Functions</navtitle></titlealts>
+
+ <titlealts audience="PDF">
+
+ <navtitle>String Functions</navtitle>
+
+ </titlealts>
+
<prolog>
<metadata>
<data name="Category" value="Impala"/>
@@ -35,20 +42,21 @@ under the License.
<conbody>
<p rev="2.0.0">
- String functions are classified as those primarily accepting or returning <codeph>STRING</codeph>,
- <codeph>VARCHAR</codeph>, or <codeph>CHAR</codeph> data types, for example to measure the length of a string
- or concatenate two strings together.
+ String functions are classified as those primarily accepting or returning
+ <codeph>STRING</codeph>, <codeph>VARCHAR</codeph>, or <codeph>CHAR</codeph> data types,
+ for example to measure the length of a string or concatenate two strings together.
<ul>
<li>
- All the functions that accept <codeph>STRING</codeph> arguments also accept the <codeph>VARCHAR</codeph>
- and <codeph>CHAR</codeph> types introduced in Impala 2.0.
+ All the functions that accept <codeph>STRING</codeph> arguments also accept the
+ <codeph>VARCHAR</codeph> and <codeph>CHAR</codeph> types introduced in Impala 2.0.
</li>
<li>
- Whenever <codeph>VARCHAR</codeph> or <codeph>CHAR</codeph> values are passed to a function that returns a
- string value, the return type is normalized to <codeph>STRING</codeph>. For example, a call to
- <codeph>concat()</codeph> with a mix of <codeph>STRING</codeph>, <codeph>VARCHAR</codeph>, and
- <codeph>CHAR</codeph> arguments produces a <codeph>STRING</codeph> result.
+ Whenever <codeph>VARCHAR</codeph> or <codeph>CHAR</codeph> values are passed to a
+ function that returns a string value, the return type is normalized to
+ <codeph>STRING</codeph>. For example, a call to <codeph>CONCAT()</codeph> with a mix
+ of <codeph>STRING</codeph>, <codeph>VARCHAR</codeph>, and <codeph>CHAR</codeph>
+ arguments produces a <codeph>STRING</codeph> result.
</li>
</ul>
</p>
@@ -56,8 +64,9 @@ under the License.
<p conref="../shared/impala_common.xml#common/related_info"/>
<p>
- The string functions operate mainly on these data types: <xref href="impala_string.xml#string"/>,
- <xref href="impala_varchar.xml#varchar"/>, and <xref href="impala_char.xml#char"/>.
+ The string functions operate mainly on these data types:
+ <xref href="impala_string.xml#string"/>, <xref href="impala_varchar.xml#varchar"/>, and
+ <xref href="impala_char.xml#char"/>.
</p>
<p>
@@ -68,18 +77,167 @@ under the License.
Impala supports the following string functions:
</p>
+ <ul>
+ <li>
+ <xref href="#string_functions/ascii">ASCII</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/base64decode">BASE64DECODE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/base64encode">BASE64ENCODE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/btrim">BTRIM</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/char_length">CHAR_LENGTH</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/chr">CHR</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/concat">CONCAT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/concat_ws">CONCAT_WS</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/find_in_set">FIND_IN_SET</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/group_concat">GROUP_CONCAT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/initcap">INITCAP</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/instr">INSTR</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/left">LEFT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/length">LENGTH</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/locate">LOCATE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/lower">LOWER, LCASE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/lpad">LPAD</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/ltrim">LTRI </xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/parse_url">PARSE_URL</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/regexp_escape">REGEXP_ESCAPE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/regexp_extract">REGEXP_EXTRACT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/regexp_like">REGEXP_LIKE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/regexp_replace">REGEXP_REPLACE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/repeat">REPEAT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/replace">REPLACE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/reverse">REVERSE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/right">RIGHT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/rpad">RPAD</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/rtrim">RTRIM</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/space">SPACE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/split_part">SPLIT_PART</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/strleft">STRLEFT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/strright">STRRIGHT</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/substr">SUBSTR, SUBSTRING</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/translate">TRANSLATE</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/trim">TRIM</xref>
+ </li>
+
+ <li>
+ <xref href="#string_functions/upper">UPPER, UCASE</xref>
+ </li>
+ </ul>
+
<dl>
<dlentry id="ascii">
<dt>
- <codeph>ascii(string str)</codeph>
+ ASCII(STRING str)
</dt>
<dd>
- <indexterm audience="hidden">ascii() function</indexterm>
<b>Purpose:</b> Returns the numeric ASCII code of the first character of the argument.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
</dd>
@@ -88,25 +246,33 @@ under the License.
<dlentry id="base64decode" rev="2.6.0 IMPALA-2107">
<dt>
- <codeph>base64decode(string str)</codeph>
+ BASE64DECODE(STRING str)
</dt>
<dd>
- <indexterm audience="hidden">base64decode() function</indexterm>
<b>Purpose:</b>
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
For general information about Base64 encoding, see
- <xref keyref="base64"/>.
+ <xref
+ keyref="base64"/>.
</p>
+
<p conref="../shared/impala_common.xml#common/base64_use_cases"/>
+
<p conref="../shared/impala_common.xml#common/base64_charset"/>
+
<p conref="../shared/impala_common.xml#common/base64_alignment"/>
+
<p conref="../shared/impala_common.xml#common/base64_error_handling"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p conref="../shared/impala_common.xml#common/base64_examples"/>
</dd>
@@ -115,24 +281,31 @@ under the License.
<dlentry id="base64encode" rev="2.6.0 IMPALA-2107">
<dt>
- <codeph>base64encode(string str)</codeph>
+ BASE64ENCODE(STRING str)
</dt>
<dd>
- <indexterm audience="hidden">base64encode() function</indexterm>
<b>Purpose:</b>
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
For general information about Base64 encoding, see
- <xref keyref="base64"/>.
+ <xref
+ keyref="base64"/>.
</p>
+
<p conref="../shared/impala_common.xml#common/base64_use_cases"/>
+
<p conref="../shared/impala_common.xml#common/base64_charset"/>
+
<p conref="../shared/impala_common.xml#common/base64_alignment"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p conref="../shared/impala_common.xml#common/base64_examples"/>
</dd>
@@ -141,32 +314,33 @@ under the License.
<dlentry rev="2.3.0" id="btrim">
<dt>
- <codeph>btrim(string a)</codeph>,
- <codeph>btrim(string a, string chars_to_trim)</codeph>
+ BTRIM(STRING a), BTRIM(STRING a, STRING chars_to_trim)
</dt>
<dd>
- <indexterm audience="hidden">btrim() function</indexterm>
- <b>Purpose:</b> Removes all instances of one or more characters
- from the start and end of a <codeph>STRING</codeph> value.
- By default, removes only spaces.
- If a non-<codeph>NULL</codeph> optional second argument is specified, the function removes all
- occurrences of characters in that second argument from the beginning and
- end of the string.
- <p><b>Return type:</b> <codeph>string</codeph></p>
+ <b>Purpose:</b> Removes all instances of one or more characters from the start and end
+ of a <codeph>STRING</codeph> value. By default, removes only spaces. If a
+ non-<codeph>NULL</codeph> optional second argument is specified, the function removes
+ all occurrences of characters in that second argument from the beginning and end of
+ the string.
+ <p>
+ <b>Return type:</b> <codeph>STRING</codeph>
+ </p>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- The following examples show the default <codeph>btrim()</codeph> behavior,
- and what changes when you specify the optional second argument.
- All the examples bracket the output value with <codeph>[ ]</codeph>
- so that you can see any leading or trailing spaces in the <codeph>btrim()</codeph> result.
- By default, the function removes and number of both leading and trailing spaces.
- When the second argument is specified, any number of occurrences of any
- character in the second argument are removed from the start and end of the
- input string; in this case, spaces are not removed (unless they are part of the second
- argument) and any instances of the characters are not removed if they do not come
- right at the beginning or end of the string.
+ The following examples show the default <codeph>BTRIM()</codeph> behavior, and what
+ changes when you specify the optional second argument. All the examples bracket the
+ output value with <codeph>[ ]</codeph> so that you can see any leading or trailing
+ spaces in the <codeph>BTRIM()</codeph> result. By default, the function removes and
+ number of both leading and trailing spaces. When the second argument is specified,
+ any number of occurrences of any character in the second argument are removed from
+ the start and end of the input string; in this case, spaces are not removed (unless
+ they are part of the second argument) and any instances of the characters are not
+ removed if they do not come right at the beginning or end of the string.
</p>
<codeblock>-- Remove multiple spaces before and one space after.
select concat('[',btrim(' hello '),']');
@@ -200,26 +374,27 @@ select concat('[',btrim('xyhelxyzlozyzzxx','xyz'),']');
<dlentry rev="1.3.0" id="char_length">
<dt>
- <codeph>char_length(string a), <ph rev="1.3.0" id="character_length">character_length(string a)</ph></codeph>
+ CHAR_LENGTH(STRING a), CHARACTER_LENGTH(STRING a)
</dt>
<dd rev="IMPALA-6391 IMPALA-2172">
- <indexterm audience="hidden">char_length() function</indexterm>
- <indexterm audience="hidden">character_length() function</indexterm>
<b>Purpose:</b> Returns the length in characters of the argument string, including any
trailing spaces that pad a <codeph>CHAR</codeph> value.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- When applied to a <codeph>STRING</codeph> value, it returns the
- same result as the <codeph>length()</codeph> function. When applied
- to a <codeph>CHAR</codeph> value, it might return a larger value
- than <codeph>length()</codeph> does, to account for trailing spaces
- in the <codeph>CHAR</codeph>.
+ When applied to a <codeph>STRING</codeph> value, it returns the same result as the
+ <codeph>length()</codeph> function. When applied to a <codeph>CHAR</codeph> value,
+ it might return a larger value than <codeph>length()</codeph> does, to account for
+ trailing spaces in the <codeph>CHAR</codeph>.
</p>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p conref="../shared/impala_common.xml#common/length_demo"/>
</dd>
@@ -228,23 +403,26 @@ select concat('[',btrim('xyhelxyzlozyzzxx','xyz'),']');
<dlentry rev="2.3.0" id="chr">
<dt>
- <codeph>chr(int character_code)</codeph>
+ CHR(INT character_code)
</dt>
<dd>
- <indexterm audience="hidden">chr() function</indexterm>
- <b>Purpose:</b> Returns a character specified by a decimal code point value.
- The interpretation and display of the resulting character depends on your system locale.
- Because consistent processing of Impala string values is only guaranteed
- for values within the ASCII range, only use this function for values
- corresponding to ASCII characters.
- In particular, parameter values greater than 255 return an empty string.
- <p><b>Return type:</b> <codeph>string</codeph></p>
- <p>
- <b>Usage notes:</b> Can be used as the inverse of the <codeph>ascii()</codeph> function, which
- converts a character to its numeric ASCII code.
+ <b>Purpose:</b> Returns a character specified by a decimal code point value. The
+ interpretation and display of the resulting character depends on your system locale.
+ Because consistent processing of Impala string values is only guaranteed for values
+ within the ASCII range, only use this function for values corresponding to ASCII
+ characters. In particular, parameter values greater than 255 return an empty string.
+ <p>
+ <b>Return type:</b> <codeph>STRING</codeph>
+ </p>
+
+ <p>
+ <b>Usage notes:</b> Can be used as the inverse of the <codeph>ascii()</codeph>
+ function, which converts a character to its numeric ASCII code.
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_230"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>SELECT chr(65);
+---------+
@@ -267,15 +445,16 @@ SELECT chr(97);
<dlentry id="concat">
<dt>
- <codeph>concat(string a, string b...)</codeph>
+ CONCAT(STRING a, STRING b...)
</dt>
<dd>
- <indexterm audience="hidden">concat() function</indexterm>
- <b>Purpose:</b> Returns a single string representing all the argument values joined together.
+ <b>Purpose:</b> Returns a single string representing all the argument values joined
+ together.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/concat_blurb"/>
</dd>
@@ -284,16 +463,16 @@ SELECT chr(97);
<dlentry id="concat_ws">
<dt>
- <codeph>concat_ws(string sep, string a, string b...)</codeph>
+ CONCAT_WS(STRING sep, STRING a, STRING b...)
</dt>
<dd>
- <indexterm audience="hidden">concat_ws() function</indexterm>
- <b>Purpose:</b> Returns a single string representing the second and following argument values joined
- together, delimited by a specified separator.
+ <b>Purpose:</b> Returns a single string representing the second and following argument
+ values joined together, delimited by a specified separator.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/concat_blurb"/>
</dd>
@@ -302,16 +481,16 @@ SELECT chr(97);
<dlentry id="find_in_set">
<dt>
- <codeph>find_in_set(string str, string strList)</codeph>
+ FIND_IN_SEt(STRING str, STRING strList)
</dt>
<dd>
- <indexterm audience="hidden">find_in_set() function</indexterm>
- <b>Purpose:</b> Returns the position (starting from 1) of the first occurrence of a specified string
- within a comma-separated string. Returns <codeph>NULL</codeph> if either argument is
- <codeph>NULL</codeph>, 0 if the search string is not found, or 0 if the search string contains a comma.
+ <b>Purpose:</b> Returns the position (starting from 1) of the first occurrence of a
+ specified string within a comma-separated string. Returns <codeph>NULL</codeph> if
+ either argument is <codeph>NULL</codeph>, 0 if the search string is not found, or 0 if
+ the search string contains a comma.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
</dd>
@@ -320,27 +499,30 @@ SELECT chr(97);
<dlentry rev="1.2" id="group_concat">
<dt>
- <codeph>group_concat(string s [, string sep])</codeph>
+ GROUP_CONCAT(STRING s [, STRING sep])
</dt>
<dd>
- <indexterm audience="hidden">group_concat() function</indexterm>
- <b>Purpose:</b> Returns a single string representing the argument value concatenated together for each
- row of the result set. If the optional separator string is specified, the separator is added between each
- pair of concatenated values.
+ <b>Purpose:</b> Returns a single string representing the argument value concatenated
+ together for each row of the result set. If the optional separator string is
+ specified, the separator is added between each pair of concatenated values.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/concat_blurb"/>
+
<p>
- By default, returns a single string covering the whole result set. To include other columns or values
- in the result set, or to produce multiple concatenated strings for subsets of rows, include a
- <codeph>GROUP BY</codeph> clause in the query.
+ By default, returns a single string covering the whole result set. To include other
+ columns or values in the result set, or to produce multiple concatenated strings for
+ subsets of rows, include a <codeph>GROUP BY</codeph> clause in the query.
</p>
+
<p>
- Strictly speaking, <codeph>group_concat()</codeph> is an aggregate function, not a scalar
- function like the others in this list.
- For additional details and examples, see <xref href="impala_group_concat.xml#group_concat"/>.
+ Strictly speaking, <codeph>GROUP_CONCAT()</codeph> is an aggregate function, not a
+ scalar function like the others in this list. For additional details and examples,
+ see <xref
+ href="impala_group_concat.xml#group_concat"/>.
</p>
</dd>
@@ -349,14 +531,13 @@ SELECT chr(97);
<dlentry rev="1.2" id="initcap">
<dt>
- <codeph>initcap(string str)</codeph>
+ INITCAP(STRING str)
</dt>
<dd>
- <indexterm audience="hidden">initcap() function</indexterm>
<b>Purpose:</b> Returns the input string with the first letter capitalized.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -365,22 +546,22 @@ SELECT chr(97);
<dlentry id="instr">
<dt>
- <codeph>instr(string str, string substr <ph rev="IMPALA-3973">[, bigint position [, bigint occurrence ] ]</ph>)</codeph>
+ INSTR(STRING str, STRING substr <ph rev="IMPALA-3973">[, BIGINT position [, BIGINT
+ occurrence ] ]</ph>)
</dt>
<dd>
- <indexterm audience="hidden">instr() function</indexterm>
- <b>Purpose:</b> Returns the position (starting from 1) of the first occurrence of a substring within a
- longer string.
+ <b>Purpose:</b> Returns the position (starting from 1) of the first occurrence of a
+ substring within a longer string.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
<p>
If the substring is not present in the string, the function returns 0:
</p>
-
<codeblock rev="IMPALA-3973 2.8.0">
select instr('foo bar bletch', 'z');
+------------------------------+
@@ -389,7 +570,6 @@ select instr('foo bar bletch', 'z');
| 0 |
+------------------------------+
</codeblock>
-
<p rev="IMPALA-3973 2.8.0">
The optional third and fourth arguments let you find instances of the substring
other than the first instance starting from the left:
@@ -397,10 +577,9 @@ select instr('foo bar bletch', 'z');
<ul>
<li>
<p>
- The third argument lets you specify a starting point within the string
- other than 1:
+ The third argument lets you specify a starting point within the string other
+ than 1:
</p>
-
<codeblock>
-- Restricting the search to positions 7..end,
-- the first occurrence of 'b' is at position 9.
@@ -420,13 +599,11 @@ select instr('foo bar bletch', 'b', 10);
| 0 |
+----------------------------------+
</codeblock>
-
<p>
- If the third argument is negative, the search works right-to-left
- starting that many characters from the right. The return value still
- represents the position starting from the left side of the string.
+ If the third argument is negative, the search works right-to-left starting that
+ many characters from the right. The return value still represents the position
+ starting from the left side of the string.
</p>
-
<codeblock rev="IMPALA-3973 2.8.0">
-- Scanning right to left, the first occurrence of 'o'
-- is at position 8. (8th character from the left.)
@@ -456,14 +633,12 @@ select instr('hello world','o',-10);
| 0 |
+--------------------------------+
</codeblock>
-
</li>
<li>
<p>
The fourth argument lets you specify an occurrence other than the first:
</p>
-
<codeblock rev="IMPALA-3973 2.8.0">
-- 2nd occurrence of 'b' is at position 9.
select instr('foo bar bletch', 'b', 1, 2);
@@ -482,12 +657,10 @@ select instr('foo bar bletch', 'b', -1, 2);
| 5 |
+-------------------------------------+
</codeblock>
-
<p>
- If the fourth argument is greater than the number of matching occurrences,
- the function returns 0:
+ If the fourth argument is greater than the number of matching occurrences, the
+ function returns 0:
</p>
-
<codeblock>
-- There is no 3rd occurrence within the string.
select instr('foo bar bletch', 'b', 1, 3);
@@ -506,12 +679,10 @@ select instr('foo bar bletch', 'b', 10, 1);
| 0 |
+-------------------------------------+
</codeblock>
-
<p>
- The fourth argument cannot be negative or zero. A non-positive value for
- this argument causes an error:
+ The fourth argument cannot be negative or zero. A non-positive value for this
+ argument causes an error:
</p>
-
<codeblock>
select instr('foo bar bletch', 'b', 1, 0);
ERROR: UDF ERROR: Invalid occurrence parameter to instr function: 0
@@ -519,15 +690,13 @@ ERROR: UDF ERROR: Invalid occurrence parameter to instr function: 0
select instr('aaaaaaaaa','aa', 1, -1);
ERROR: UDF ERROR: Invalid occurrence parameter to instr function: -1
</codeblock>
-
</li>
<li>
<p>
- If either of the optional arguments is <codeph>NULL</codeph>,
- the function also returns <codeph>NULL</codeph>:
+ If either of the optional arguments is <codeph>NULL</codeph>, the function also
+ returns <codeph>NULL</codeph>:
</p>
-
<codeblock>
select instr('foo bar bletch', 'b', null);
+------------------------------------+
@@ -544,51 +713,56 @@ select instr('foo bar bletch', 'b', 1, null);
+---------------------------------------+
</codeblock>
</li>
-
</ul>
-
</dd>
</dlentry>
+
<dlentry id="left">
+
<dt>
- <codeph>left(string a, int num_chars)</codeph>
+ LEFT(STRING a, INT num_chars)
</dt>
+
<dd>
- See the <codeph>strleft</codeph> function.
+ See the <codeph>STRLEFT()</codeph> function.
</dd>
+
</dlentry>
<dlentry id="length">
<dt>
- <codeph>length(string a)</codeph>
+ LENGTH(STRING a)
</dt>
<dd rev="IMPALA-6391 IMPALA-2172">
- <indexterm audience="hidden">length() function</indexterm>
- <b>Purpose:</b> Returns the length in characters of the argument string,
- ignoring any trailing spaces in <codeph>CHAR</codeph> values.
+ <b>Purpose:</b> Returns the length in characters of the argument string, ignoring any
+ trailing spaces in <codeph>CHAR</codeph> values.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- When applied to a <codeph>STRING</codeph> value, it returns the
- same result as the <codeph>char_length()</codeph> function. When applied
- to a <codeph>CHAR</codeph> value, it might return a smaller value
- than <codeph>char_length()</codeph> does, because <codeph>length()</codeph>
- ignores any trailing spaces in the <codeph>CHAR</codeph>.
+ When applied to a <codeph>STRING</codeph> value, it returns the same result as the
+ <codeph>CHAR_LENGTH()</codeph> function. When applied to a <codeph>CHAR</codeph>
+ value, it might return a smaller value than <codeph>CHAR_LENGTH()</codeph> does,
+ because <codeph>LENGTH()</codeph> ignores any trailing spaces in the
+ <codeph>CHAR</codeph>.
</p>
+
<note>
- Because the behavior of <codeph>length()</codeph> with <codeph>CHAR</codeph>
- values containing trailing spaces is not standardized across the industry,
- when porting code from other database systems, evaluate the behavior of
- <codeph>length()</codeph> on the source system and switch to
- <codeph>char_length()</codeph> for Impala if necessary.
+ Because the behavior of <codeph>LENGTH()</codeph> with <codeph>CHAR</codeph> values
+ containing trailing spaces is not standardized across the industry, when porting
+ code from other database systems, evaluate the behavior of <codeph>LENGTH()</codeph>
+ on the source system and switch to <codeph>CHAR_LENGTH()</codeph> for Impala if
+ necessary.
</note>
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p conref="../shared/impala_common.xml#common/length_demo"/>
</dd>
@@ -597,15 +771,14 @@ select instr('foo bar bletch', 'b', 1, null);
<dlentry id="locate">
<dt>
- <codeph>locate(string substr, string str[, int pos])</codeph>
+ LOCATE(STRING substr, STRING str[, INT pos])
</dt>
<dd>
- <indexterm audience="hidden">locate() function</indexterm>
- <b>Purpose:</b> Returns the position (starting from 1) of the first occurrence of a substring within a
- longer string, optionally after a particular position.
+ <b>Purpose:</b> Returns the position (starting from 1) of the first occurrence of a
+ substring within a longer string, optionally after a particular position.
<p>
- <b>Return type:</b> <codeph>int</codeph>
+ <b>Return type:</b> <codeph>INT</codeph>
</p>
</dd>
@@ -614,17 +787,20 @@ select instr('foo bar bletch', 'b', 1, null);
<dlentry id="lower">
<dt>
- <codeph>lower(string a), <ph id="lcase">lcase(string a)</ph> </codeph>
+ LOWER(STRING a), <ph id="lcase">LCASE(STRING a)</ph>
</dt>
<dd>
- <indexterm audience="hidden">lower() function</indexterm>
<b>Purpose:</b> Returns the argument string converted to all-lowercase.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p conref="../shared/impala_common.xml#common/case_insensitive_comparisons_tip"/>
+
+ <p
+ conref="../shared/impala_common.xml#common/case_insensitive_comparisons_tip"
+ />
</dd>
</dlentry>
@@ -632,16 +808,16 @@ select instr('foo bar bletch', 'b', 1, null);
<dlentry id="lpad">
<dt>
- <codeph>lpad(string str, int len, string pad)</codeph>
+ LPAD(STRING str, INT len, STRING pad)
</dt>
<dd>
- <indexterm audience="hidden">lpad() function</indexterm>
- <b>Purpose:</b> Returns a string of a specified length, based on the first argument string. If the
- specified string is too short, it is padded on the left with a repeating sequence of the characters from
- the pad string. If the specified string is too long, it is truncated on the right.
+ <b>Purpose:</b> Returns a string of a specified length, based on the first argument
+ string. If the specified string is too short, it is padded on the left with a
+ repeating sequence of the characters from the pad string. If the specified string is
+ too long, it is truncated on the right.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -650,16 +826,15 @@ select instr('foo bar bletch', 'b', 1, null);
<dlentry id="ltrim">
<dt>
- <codeph>ltrim(string a [, string chars_to_trim])</codeph>
+ LTRIM(STRING a [, STRING chars_to_trim])
</dt>
<dd>
- <indexterm audience="hidden">ltrim() function</indexterm>
- <b>Purpose:</b> Returns the argument string with all occurrences
- of characters specified by the second argument removed from
- the left side. Removes spaces if the second argument is not specified.
+ <b>Purpose:</b> Returns the argument string with all occurrences of characters
+ specified by the second argument removed from the left side. Removes spaces if the
+ second argument is not specified.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -668,26 +843,29 @@ select instr('foo bar bletch', 'b', 1, null);
<dlentry id="parse_url">
<dt>
- <codeph>parse_url(string urlString, string partToExtract [, string keyToExtract])</codeph>
+ PARSE_URL(STRING urlString, STRING partToExtract [, STRING keyToExtract])
</dt>
<dd>
<indexterm audience="hidden">parse_url() function</indexterm>
- <b>Purpose:</b> Returns the portion of a URL corresponding to a specified part. The part argument can be
- <codeph>'PROTOCOL'</codeph>, <codeph>'HOST'</codeph>, <codeph>'PATH'</codeph>, <codeph>'REF'</codeph>,
- <codeph>'AUTHORITY'</codeph>, <codeph>'FILE'</codeph>, <codeph>'USERINFO'</codeph>, or
- <codeph>'QUERY'</codeph>. Uppercase is required for these literal values. When requesting the
- <codeph>QUERY</codeph> portion of the URL, you can optionally specify a key to retrieve just the
- associated value from the key-value pairs in the query string.
+ <b>Purpose:</b> Returns the portion of a URL corresponding to a specified part. The
+ part argument can be <codeph>'PROTOCOL'</codeph>, <codeph>'HOST'</codeph>,
+ <codeph>'PATH'</codeph>, <codeph>'REF'</codeph>, <codeph>'AUTHORITY'</codeph>,
+ <codeph>'FILE'</codeph>, <codeph>'USERINFO'</codeph>, or <codeph>'QUERY'</codeph>.
+ Uppercase is required for these literal values. When requesting the
+ <codeph>QUERY</codeph> portion of the URL, you can optionally specify a key to
+ retrieve just the associated value from the key-value pairs in the query string.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p>
- <b>Usage notes:</b> This function is important for the traditional Hadoop use case of interpreting web
- logs. For example, if the web traffic data features raw URLs not divided into separate table columns,
- you can count visitors to a particular page by extracting the <codeph>'PATH'</codeph> or
- <codeph>'FILE'</codeph> field, or analyze search terms by extracting the corresponding key from the
- <codeph>'QUERY'</codeph> field.
+ <b>Usage notes:</b> This function is important for the traditional Hadoop use case
+ of interpreting web logs. For example, if the web traffic data features raw URLs not
+ divided into separate table columns, you can count visitors to a particular page by
+ extracting the <codeph>'PATH'</codeph> or <codeph>'FILE'</codeph> field, or analyze
+ search terms by extracting the corresponding key from the <codeph>'QUERY'</codeph>
+ field.
</p>
</dd>
@@ -696,26 +874,27 @@ select instr('foo bar bletch', 'b', 1, null);
<dlentry rev="3.0" id="regexp_escape">
<dt>
- <codeph>regexp_escape(string source)</codeph>
+ REGEXP_ESCAPE(STRING source)
</dt>
<dd>
- <b>Purpose:</b> The <codeph>regexp_escape</codeph> function returns
- a string escaped for the special character in RE2 library so that the
- special characters are interpreted literally rather than as special
- characters. The following special characters are escaped by the
- function:
+ <b>Purpose:</b> The <codeph>REGEXP_ESCAPE()</codeph> function returns a string escaped
+ for the special character in RE2 library so that the special characters are
+ interpreted literally rather than as special characters. The following special
+ characters are escaped by the function:
<codeblock><![CDATA[.\+*?[^]$(){}=!<>|:-]]></codeblock>
-
<p>
- <b>Return type:</b>
- <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
<p conref="../shared/impala_common.xml#common/regexp_re2"/>
+
<p conref="../shared/impala_common.xml#common/regexp_re2_warning"/>
+
<p conref="../shared/impala_common.xml#common/regexp_escapes"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
This example shows escaping one of special characters in RE2.
</p>
@@ -744,24 +923,28 @@ select instr('foo bar bletch', 'b', 1, null);
<dlentry id="regexp_extract">
<dt>
- <codeph>regexp_extract(string subject, string pattern, int index)</codeph>
+ REGEXP_EXTRACT(STRING subject, STRING pattern, INT index)
</dt>
<dd>
- <indexterm audience="hidden">regexp_extract() function</indexterm>
- <b>Purpose:</b> Returns the specified () group from a string based on a regular expression pattern. Group
- 0 refers to the entire extracted string, while group 1, 2, and so on refers to the first, second, and so
- on <codeph>(...)</codeph> portion.
+ <b>Purpose:</b> Returns the specified () group from a string based on a regular
+ expression pattern. Group 0 refers to the entire extracted string, while group 1, 2,
+ and so on refers to the first, second, and so on <codeph>(...)</codeph> portion.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/regexp_re2"/>
+
<p conref="../shared/impala_common.xml#common/regexp_re2_warning"/>
+
<p conref="../shared/impala_common.xml#common/regexp_escapes"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- This example shows how group 0 matches the full pattern string, including the portion outside any
- <codeph>()</codeph> group:
+ This example shows how group 0 matches the full pattern string, including the
+ portion outside any <codeph>()</codeph> group:
</p>
<codeblock>[localhost:21000] > select regexp_extract('abcdef123ghi456jkl','.*?(\\d+)',0);
+------------------------------------------------------+
@@ -771,8 +954,8 @@ select instr('foo bar bletch', 'b', 1, null);
+------------------------------------------------------+
Returned 1 row(s) in 0.11s</codeblock>
<p>
- This example shows how group 1 matches just the contents inside the first <codeph>()</codeph> group in
- the pattern string:
+ This example shows how group 1 matches just the contents inside the first
+ <codeph>()</codeph> group in the pattern string:
</p>
<codeblock>[localhost:21000] > select regexp_extract('abcdef123ghi456jkl','.*?(\\d+)',1);
+------------------------------------------------------+
@@ -782,12 +965,13 @@ Returned 1 row(s) in 0.11s</codeblock>
+------------------------------------------------------+
Returned 1 row(s) in 0.11s</codeblock>
<p rev="2.0.0">
- Unlike in earlier Impala releases, the regular expression library used in Impala 2.0 and later supports
- the <codeph>.*?</codeph> idiom for non-greedy matches. This example shows how a pattern string starting
- with <codeph>.*?</codeph> matches the shortest possible portion of the source string, returning the
- rightmost set of lowercase letters. A pattern string both starting and ending with <codeph>.*?</codeph>
- finds two potential matches of equal length, and returns the first one found (the leftmost set of
- lowercase letters).
+ Unlike in earlier Impala releases, the regular expression library used in Impala 2.0
+ and later supports the <codeph>.*?</codeph> idiom for non-greedy matches. This
+ example shows how a pattern string starting with <codeph>.*?</codeph> matches the
+ shortest possible portion of the source string, returning the rightmost set of
+ lowercase letters. A pattern string both starting and ending with
+ <codeph>.*?</codeph> finds two potential matches of equal length, and returns the
+ first one found (the leftmost set of lowercase letters).
</p>
<codeblock>[localhost:21000] > select regexp_extract('AbcdBCdefGHI','.*?([[:lower:]]+)',1);
+--------------------------------------------------------+
@@ -809,48 +993,58 @@ Returned 1 row(s) in 0.11s</codeblock>
<dlentry rev="2.3.0" id="regexp_like">
<dt>
- <codeph>regexp_like(string source, string pattern[, string options])</codeph>
+ REGEXP_LIKE(STRING source, STRING pattern[, STRING options])
</dt>
<dd>
- <indexterm audience="hidden">regexp_like() function</indexterm>
<b>Purpose:</b> Returns <codeph>true</codeph> or <codeph>false</codeph> to indicate
- whether the source string contains anywhere inside it the regular expression given by the pattern.
- The optional third argument consists of letter flags that change how the match is performed,
- such as <codeph>i</codeph> for case-insensitive matching.
- <p conref="../shared/impala_common.xml#common/syntax_blurb"/>
+ whether the source string contains anywhere inside it the regular expression given by
+ the pattern. The optional third argument consists of letter flags that change how the
+ match is performed, such as <codeph>i</codeph> for case-insensitive matching.
+ <p
+ conref="../shared/impala_common.xml#common/syntax_blurb"/>
+
<p>
The flags that you can include in the optional third argument are:
</p>
<ul>
- <li>
- <codeph>c</codeph>: Case-sensitive matching (the default).
- </li>
- <li>
- <codeph>i</codeph>: Case-insensitive matching. If multiple instances of <codeph>c</codeph> and <codeph>i</codeph>
- are included in the third argument, the last such option takes precedence.
- </li>
- <li>
- <codeph>m</codeph>: Multi-line matching. The <codeph>^</codeph> and <codeph>$</codeph>
- operators match the start or end of any line within the source string, not the
- start and end of the entire string.
- </li>
- <li>
- <codeph>n</codeph>: Newline matching. The <codeph>.</codeph> operator can match the
- newline character. A repetition operator such as <codeph>.*</codeph> can
- match a portion of the source string that spans multiple lines.
- </li>
+ <li>
+ <codeph>c</codeph>: Case-sensitive matching (the default).
+ </li>
+
+ <li>
+ <codeph>i</codeph>: Case-insensitive matching. If multiple instances of
+ <codeph>c</codeph> and <codeph>i</codeph> are included in the third argument, the
+ last such option takes precedence.
+ </li>
+
+ <li>
+ <codeph>m</codeph>: Multi-line matching. The <codeph>^</codeph> and
+ <codeph>$</codeph> operators match the start or end of any line within the source
+ string, not the start and end of the entire string.
+ </li>
+
+ <li>
+ <codeph>n</codeph>: Newline matching. The <codeph>.</codeph> operator can match
+ the newline character. A repetition operator such as <codeph>.*</codeph> can match
+ a portion of the source string that spans multiple lines.
+ </li>
</ul>
<p>
- <b>Return type:</b> <codeph>boolean</codeph>
+ <b>Return type:</b> <codeph>BOOLEAN</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/regexp_re2"/>
+
<p conref="../shared/impala_common.xml#common/regexp_re2_warning"/>
+
<p conref="../shared/impala_common.xml#common/regexp_escapes"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- This example shows how <codeph>regexp_like()</codeph> can test for the existence
- of various kinds of regular expression patterns within a source string:
+ This example shows how <codeph>regexp_like()</codeph> can test for the existence of
+ various kinds of regular expression patterns within a source string:
</p>
<codeblock><![CDATA[
-- Matches because the 'f' appears somewhere in 'foo'.
@@ -915,26 +1109,31 @@ select regexp_like('foooooobar','fx*y*o*b');
<dlentry id="regexp_replace">
<dt>
- <codeph>regexp_replace(string initial, string pattern, string replacement)</codeph>
+ REGEXP_REPLACE(STRING initial, STRING pattern, STRING replacement)
</dt>
<dd>
- <indexterm audience="hidden">regexp_replace() function</indexterm>
- <b>Purpose:</b> Returns the initial argument with the regular expression pattern replaced by the final
- argument string.
+ <b>Purpose:</b> Returns the initial argument with the regular expression pattern
+ replaced by the final argument string.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/regexp_re2"/>
+
<p conref="../shared/impala_common.xml#common/regexp_re2_warning"/>
+
<p conref="../shared/impala_common.xml#common/regexp_escapes"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- These examples show how you can replace parts of a string matching a pattern with replacement text,
- which can include backreferences to any <codeph>()</codeph> groups in the pattern string. The
- backreference numbers start at 1, and any <codeph>\</codeph> characters must be escaped as
- <codeph>\\</codeph>.
+ These examples show how you can replace parts of a string matching a pattern with
+ replacement text, which can include backreferences to any <codeph>()</codeph> groups
+ in the pattern string. The backreference numbers start at 1, and any
+ <codeph>\</codeph> characters must be escaped as <codeph>\\</codeph>.
</p>
+
<p>
Replace a character pattern with new text:
</p>
@@ -946,7 +1145,8 @@ select regexp_like('foooooobar','fx*y*o*b');
+------------------------------------------+
Returned 1 row(s) in 0.11s</codeblock>
<p>
- Replace a character pattern with substitution text that includes the original matching text:
+ Replace a character pattern with substitution text that includes the original
+ matching text:
</p>
<codeblock>[localhost:21000] > select regexp_replace('aaabbbaaa','(b+)','<\\1>');
+----------------------------------------------+
@@ -972,14 +1172,13 @@ Returned 1 row(s) in 0.12s</codeblock>
<dlentry id="repeat">
<dt>
- <codeph>repeat(string str, int n)</codeph>
+ REPEAT(STRING str, INT n)
</dt>
<dd>
- <indexterm audience="hidden">repeat() function</indexterm>
<b>Purpose:</b> Returns the argument string repeated a specified number of times.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -988,33 +1187,39 @@ Returned 1 row(s) in 0.12s</codeblock>
<dlentry id="replace" rev="2.9.0 IMPALA-4729">
<dt>
- <codeph>replace(string initial, string target, string replacement)</codeph>
+ REPLACE(STRING initial, STRING target, STRING replacement)
</dt>
<dd>
- <indexterm audience="hidden">replace() function</indexterm>
<b>Purpose:</b> Returns the initial argument with all occurrences of the target string
replaced by the replacement string.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
+
<p>
- Because this function does not use any regular expression patterns, it is typically faster
- than <codeph>regexp_replace()</codeph> for simple string substitutions.
+ Because this function does not use any regular expression patterns, it is typically
+ faster than <codeph>regexp_replace()</codeph> for simple string substitutions.
</p>
+
<p>
If any argument is <codeph>NULL</codeph>, the return value is <codeph>NULL</codeph>.
</p>
+
<p>
Matching is case-sensitive.
</p>
+
<p>
- If the replacement string contains another instance of the target
- string, the expansion is only performed once, instead of
- applying again to the newly constructed string.
+ If the replacement string contains another instance of the target string, the
+ expansion is only performed once, instead of applying again to the newly constructed
+ string.
</p>
+
<p conref="../shared/impala_common.xml#common/added_in_290"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
<codeblock>-- Replace one string with another.
select replace('hello world','world','earth');
@@ -1047,40 +1252,43 @@ select replace('hello world','xyz','abc');
<dlentry id="reverse">
<dt>
- <codeph>reverse(string a)</codeph>
+ REVERSE(STRING a)
</dt>
<dd>
- <indexterm audience="hidden">reverse() function</indexterm>
<b>Purpose:</b> Returns the argument string with characters in reversed order.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
</dlentry>
+
<dlentry id="right">
+
<dt>
- <codeph>right(string a, int num_chars)</codeph>
+ RIGHT(STRING a, INT num_chars)
</dt>
+
<dd>
- See the <codeph>strright</codeph> function.
+ See the <codeph>STRRIGHT()</codeph> function.
</dd>
+
</dlentry>
<dlentry id="rpad">
<dt>
- <codeph>rpad(string str, int len, string pad)</codeph>
+ RPAD(STRING str, INT len, STRING pad)
</dt>
<dd>
- <indexterm audience="hidden">rpad() function</indexterm>
- <b>Purpose:</b> Returns a string of a specified length, based on the first argument string. If the
- specified string is too short, it is padded on the right with a repeating sequence of the characters from
- the pad string. If the specified string is too long, it is truncated on the right.
+ <b>Purpose:</b> Returns a string of a specified length, based on the first argument
+ string. If the specified string is too short, it is padded on the right with a
+ repeating sequence of the characters from the pad string. If the specified string is
+ too long, it is truncated on the right.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -1089,16 +1297,15 @@ select replace('hello world','xyz','abc');
<dlentry id="rtrim">
<dt>
- <codeph>rtrim(string a [, string chars_to_trim])</codeph>
+ RTRIM(STRING a [, STRING chars_to_trim])
</dt>
<dd>
- <indexterm audience="hidden">rtrim() function</indexterm>
- <b>Purpose:</b> Returns the argument string with all occurrences
- of characters specified by the second argument removed from
- the right side. Removes spaces if the second argument is not specified.
+ <b>Purpose:</b> Returns the argument string with all occurrences of characters
+ specified by the second argument removed from the right side. Removes spaces if the
+ second argument is not specified.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -1107,15 +1314,14 @@ select replace('hello world','xyz','abc');
<dlentry id="space">
<dt>
- <codeph>space(int n)</codeph>
+ SPACE(INT n)
</dt>
<dd>
- <indexterm audience="hidden">space() function</indexterm>
- <b>Purpose:</b> Returns a concatenated string of the specified number of spaces. Shorthand for
- <codeph>repeat(' ',<varname>n</varname>)</codeph>.
+ <b>Purpose:</b> Returns a concatenated string of the specified number of spaces.
+ Shorthand for <codeph>REPEAT(' ',<varname>n</varname>)</codeph>.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -1124,25 +1330,28 @@ select replace('hello world','xyz','abc');
<dlentry rev="2.3.0 IMPALA-2084" id="split_part">
<dt>
- <codeph>split_part(string source, string delimiter, bigint n)</codeph>
+ SPLIT_PART(STRING source, STRING delimiter, BIGINT n)
</dt>
<dd>
- <indexterm audience="hidden">split_part() function</indexterm>
- <b>Purpose:</b> Returns the nth field within a delimited string. The
- fields are numbered starting from 1. The delimiter can consist of
- multiple characters, not just a single character. All matching of the
- delimiter is done exactly, not using any regular expression patterns.
+ <b>Purpose:</b> Returns the nth field within a delimited string. The fields are
+ numbered starting from 1. The delimiter can consist of multiple characters, not just a
+ single character. All matching of the delimiter is done exactly, not using any regular
+ expression patterns.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/regexp_re2"/>
+
<p conref="../shared/impala_common.xml#common/regexp_re2_warning"/>
+
<p conref="../shared/impala_common.xml#common/regexp_escapes"/>
+
<p conref="../shared/impala_common.xml#common/example_blurb"/>
+
<p>
- These examples show how to retrieve the nth field from a delimited
- string:
+ These examples show how to retrieve the nth field from a delimited string:
</p>
<codeblock><![CDATA[
select split_part('x,y,z',',',1);
@@ -1168,10 +1377,10 @@ select split_part('x,y,z',',',3);
]]>
</codeblock>
<p>
- These examples show what happens for out-of-range field positions.
- Specifying a value less than 1 produces an error. Specifying a value
- greater than the number of fields returns a zero-length string
- (which is not the same as <codeph>NULL</codeph>).
+ These examples show what happens for out-of-range field positions. Specifying a
+ value less than 1 produces an error. Specifying a value greater than the number of
+ fields returns a zero-length string (which is not the same as
+ <codeph>NULL</codeph>).
</p>
<codeblock><![CDATA[
select split_part('x,y,z',',',0);
@@ -1216,32 +1425,30 @@ select split_part('one\|/two\|/three','\|/',3);
<dlentry id="strleft">
<dt>
- <codeph>strleft(string a, int num_chars)</codeph>
+ STRLEFT(STRING a, INT num_chars)
</dt>
<dd>
- <indexterm audience="hidden">strleft() function</indexterm>
<b>Purpose:</b> Returns the leftmost characters of the string. Shorthand for a call to
- <codeph>substr()</codeph> with 2 arguments.
+ <codeph>SUBSTR()</codeph> with 2 arguments.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
-
</dd>
+
</dlentry>
<dlentry id="strright">
<dt>
- <codeph>strright(string a, int num_chars)</codeph>
+ STRRIGHT(STRING a, INT num_chars)
</dt>
<dd>
- <indexterm audience="hidden">strright() function</indexterm>
- <b>Purpose:</b> Returns the rightmost characters of the string. Shorthand for a call to
- <codeph>substr()</codeph> with 2 arguments.
+ <b>Purpose:</b> Returns the rightmost characters of the string. Shorthand for a call
+ to <codeph>SUBSTR()</codeph> with 2 arguments.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -1250,16 +1457,17 @@ select split_part('one\|/two\|/three','\|/',3);
<dlentry id="substr">
<dt>
- <codeph>substr(string a, int start [, int len]), <ph id="substring">substring(string a, int start [, int
- len])</ph></codeph>
+ SUBSTR(STRING a, INT start [, INT len]),
+ <ph id="substring"
+ >SUBSTRING(STRING a, INT start [, INT len])</ph>
</dt>
<dd>
- <indexterm audience="hidden">substr() function</indexterm>
- <b>Purpose:</b> Returns the portion of the string starting at a specified point, optionally with a
- specified maximum length. The characters in the string are indexed starting at 1.
+ <b>Purpose:</b> Returns the portion of the string starting at a specified point,
+ optionally with a specified maximum length. The characters in the string are indexed
+ starting at 1.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -1268,43 +1476,65 @@ select split_part('one\|/two\|/three','\|/',3);
<dlentry id="translate">
<dt>
- <codeph>translate(string input, string from, string to)</codeph>
+ TRANSLATE(STRING input, STRING from, STRING to)
</dt>
<dd>
- <b>Purpose:</b> Returns the <codeph>input</codeph> string with each
- character in the <codeph>from</codeph> argument replaced with the
- corresponding character in the <codeph>to</codeph> argument. The
- characters are matched in the order they appear in
- <codeph>from</codeph> and <codeph>to</codeph>. <p> For example:
- <codeph>translate ('hello world','world','earth')</codeph> returns
- <codeph>'hetta earth'</codeph>. </p>
+ <b>Purpose:</b> Returns the <codeph>input</codeph> string with each character in the
+ <codeph>from</codeph> argument replaced with the corresponding character in the
+ <codeph>to</codeph> argument. The characters are matched in the order they appear in
+ <codeph>from</codeph> and <codeph>to</codeph>.
+ <p>
+ For example: <codeph>translate ('hello world','world','earth')</codeph> returns
+ <codeph>'hetta earth'</codeph>.
+ </p>
+
<p>
- <b>Return type:</b>
- <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p>
<b>Usage notes:</b>
</p>
- <p> If <codeph>from</codeph> contains more characters than
- <codeph>to</codeph>, the <codeph>from</codeph> characters that are
- beyond the length of <codeph>to</codeph> are removed in the result. </p>
- <p> For example: </p>
- <p>
- <codeph>translate('abcdedg', 'bcd', '1')</codeph> returns
- <codeph>'a1eg'</codeph>. </p>
- <p><codeph>translate('Unit Number#2', '# ', '_')</codeph> returns
- <codeph>'UnitNumber_2'</codeph>. </p>
- <p> If <codeph>from</codeph> is <codeph>NULL</codeph>, the function
- returns <codeph>NULL</codeph>. </p>
- <p> If <codeph>to</codeph> contains more characters than
- <codeph>from</codeph>, the extra characters in <codeph>to</codeph>
- are ignored. </p>
- <p> If <codeph>from</codeph> contains duplicate characters, the
- duplicate character is replaced with the first matching character in
- <codeph>to</codeph>. </p>
- <p> For example: <codeph>translate ('hello','ll','67')</codeph>
- returns <codeph>'he66o'</codeph>. </p>
+
+ <p>
+ If <codeph>from</codeph> contains more characters than <codeph>to</codeph>, the
+ <codeph>from</codeph> characters that are beyond the length of <codeph>to</codeph>
+ are removed in the result.
+ </p>
+
+ <p>
+ For example:
+ </p>
+
+ <p>
+ <codeph>translate('abcdedg', 'bcd', '1')</codeph> returns <codeph>'a1eg'</codeph>.
+ </p>
+
+ <p>
+ <codeph>translate('Unit Number#2', '# ', '_')</codeph> returns
+ <codeph>'UnitNumber_2'</codeph>.
+ </p>
+
+ <p>
+ If <codeph>from</codeph> is <codeph>NULL</codeph>, the function returns
+ <codeph>NULL</codeph>.
+ </p>
+
+ <p>
+ If <codeph>to</codeph> contains more characters than <codeph>from</codeph>, the
+ extra characters in <codeph>to</codeph> are ignored.
+ </p>
+
+ <p>
+ If <codeph>from</codeph> contains duplicate characters, the duplicate character is
+ replaced with the first matching character in <codeph>to</codeph>.
+ </p>
+
+ <p>
+ For example: <codeph>translate ('hello','ll','67')</codeph> returns
+ <codeph>'he66o'</codeph>.
+ </p>
</dd>
</dlentry>
@@ -1312,19 +1542,22 @@ select split_part('one\|/two\|/three','\|/',3);
<dlentry id="trim">
<dt>
- <codeph>trim(string a)</codeph>
+ TRIM(STRING a)
</dt>
<dd>
- <indexterm audience="hidden">trim() function</indexterm>
- <b>Purpose:</b> Returns the input string with both leading and trailing spaces removed. The same as
- passing the string through both <codeph>ltrim()</codeph> and <codeph>rtrim()</codeph>.
+ <b>Purpose:</b> Returns the input string with both leading and trailing spaces
+ removed. The same as passing the string through both <codeph>LTRIM()</codeph> and
+ <codeph>RTRIM()</codeph>.
<p>
- <b>Usage notes:</b> Often used during data cleansing operations during the ETL cycle, if input values might still have surrounding spaces.
- For a more general-purpose function that can remove other leading and trailing characters besides spaces, see <codeph>btrim()</codeph>.
+ <b>Usage notes:</b> Often used during data cleansing operations during the ETL
+ cycle, if input values might still have surrounding spaces. For a more
+ general-purpose function that can remove other leading and trailing characters
+ besides spaces, see <codeph>BTRIM()</codeph>.
</p>
+
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
</dd>
@@ -1333,21 +1566,25 @@ select split_part('one\|/two\|/three','\|/',3);
<dlentry id="upper">
<dt>
- <codeph>upper(string a), <ph id="ucase">ucase(string a)</ph></codeph>
+ UPPER(STRING a), <ph id="ucase">UCASE(STRING a)</ph>
</dt>
<dd>
- <indexterm audience="hidden">upper() function</indexterm>
- <indexterm audience="hidden">ucase() function</indexterm>
<b>Purpose:</b> Returns the argument string converted to all-uppercase.
<p>
- <b>Return type:</b> <codeph>string</codeph>
+ <b>Return type:</b> <codeph>STRING</codeph>
</p>
+
<p conref="../shared/impala_common.xml#common/usage_notes_blurb"/>
- <p conref="../shared/impala_common.xml#common/case_insensitive_comparisons_tip"/>
+
+ <p
+ conref="../shared/impala_common.xml#common/case_insensitive_comparisons_tip"
+ />
</dd>
</dlentry>
</dl>
+
</conbody>
+
</concept>