-
In any column expression, a wildcard like
*can be used to specify all columns, while<table name/alias>.*can be used to specify all columns from the given table. -
The
EXCLUDEfunction can be used to list columns to exclude from the wildcard expression it follows; for instance, the following can be used to select all columns from the employee table except for thessn&date_of_birthcolumns:EXCLUDE Example -
Table & column names can be double-quoted to use reserved words, e.g.,
"PERCENT"; or to use numbers or special characters in column names, e.g.,"1234"or"key:value". -
TOP <n>returns the first n records (up to 20000 records by default). -
The grouping expression list may contain column names, aliases,
expressions, or positions (e.g.,
GROUP BY 2to aggregate on the 2nd column in theSELECTlist). -
The having expression list may contain grouping expressions or any
grouping expression aliases defined in the
SELECTlist. -
The ordering expression list may contain column names, expressions, or
column positions (e.g.,
ORDER BY 2to aggregate on the 2nd column in theSELECTlist). The default ordering isASC. The default null ordering isNULLS FIRSTwhen using ascending order andNULLS LASTwhen using descending order. The general format for each comma-separated ordering expression in the list is:ORDER BY Expression Syntax -
LIMITapplies paging to the result set, starting at the 0-based offset (if specified) and returning num rows records.
Tableless Query
A query without aFROM clause can be used to return a single row of data
containing a constant or expression.
For example, to select the current day of the week:
Join
The supported join types are:INNER JOIN- matching rows between two tables[LEFT] SEMI JOIN- rows in the left-hand table that have matching rows in the right-hand tableLEFT [OUTER] JOIN- matching rows between two tables, and rows in the left-hand table that have no matching rows in the right-hand tableRIGHT [OUTER] JOIN- matching rows between two tables, and rows in the right-hand table that have no matching rows in the left-hand tableFULL [OUTER] JOINmatching rows between two tables, and rows in both tables that have no matching rows in the otherCROSS JOIN- every row in one table paired with every row in the other
- Local - highly performant, but native join criteria must be met
- Distributed - highly flexible, as native join restrictions are lifted, but less performant due to interprocessor communication overhead and requires more memory & disk space to process
JOIN ... ON and WHERE clause syntax for
inner joins; all outer join types (LEFT, RIGHT, & FULL OUTER)
require JOIN ... ON syntax.
For example, to list the name of each employee and the name of the employee’s
manager, using the WHERE clause to specify the join condition:
JOIN ... ON syntax to specify the
join condition:
ASOF
Kinetica supports the notion of an inexact match join via theASOF
join function. This feature allows each left-side table record to be matched
to a single right-side table record whose join column value is the smallest or
largest value within a range relative to the left-side join column value. In
the case where multiple right-side table records have the same smallest or
largest value for a given left-side table record, only one of the right-side
table records will be chosen (non-deterministically) and returned as part of the
join.
left_column- name of the column to join on from the left-side tableright_column- name of the column to join on from the right-side tablerel_range_begin- constant value defining the position, relative to each left-side column value, of the beginning of the range in which to match right-side column values; use a negative constant to begin the range before the left-side column value, or a positive one to begin after itrel_range_end- constant value defining the position, relative to each left-side column value, of the end of the range in which to match right-side column values; use a negative constant to end the range before the left-side column value, or a positive one to end after itMIN|MAX- useMINto return the right-side matched record with the smallest join column value; useMAXto return the right-side matched record with the greatest join column value
>=<left-side column value>+ rel_range_begin<=<left-side column value>+ rel_range_end
ASOF joins are unsupported on some materialized views.
In these situations, the materialized view can be recreated with the
KI_HINT_PROJECT_MATERIALIZED_VIEW hint to allow it to be used in an
ASOF join.Examples
The followingASOF call might be used to list, for each flight arrival time,
the soonest flight departure time that occurs between half an hour and an hour
and a half after the arrival; effectively, the time-matching portion of a
connecting flight query:
ASOF call returns right-side locations that are nearest eastward to
each left-side location, for locations within 5 degrees of the left-side:
ASOF join function can only be used as part of a join, it can
effectively be made into a filter condition by sub-selecting the filter criteria
in the FROM clause and joining on that criteria.
For instance, to look up the stock price for a given company as of a given date:
Aggregation
TheGROUP BY clause can be used to segment data into groups and apply
aggregate functions over the values within
each group. Aggregation functions applied to data without a GROUP BY clause
will be applied over the entire result set.
GROUP BY can operate on columns, column expressions, column
aliases, or the position of a member of the SELECT clause (where
1 is the first element).Grouping
TheGROUP BY clause can also be used to apply the following
grouping functions over the values within each
group:
With each of these, the GROUPING() aggregate function can be used to
distinguish aggregated null values in the data from null values generated by
the ROLLUP, CUBE, or GROUPING SETS grouping function.
For instance, the following CASE will turn the aggregated null values in
the Sector column into an <UNKNOWN SECTOR> group and the null value
generated by the grouping function into an <ALL SECTORS> group:
ROLLUP
The ROLLUP(expr list) function calculates n + 1 aggregates for n number of columns inexpr list.
For example, the following query will aggregate the average opening stock price
for these groups:
- Each market sector & stock symbol pair
- Each market sector
- All sectors and symbols
CUBE
The CUBE(expr list) function calculates 2n aggregates for n number of columns inexpr list.
For example, the following query will aggregate the average opening stock price
for these groups:
- Each market sector & stock symbol pair
- Each market sector
- Each stock symbol
- All sectors and symbols
GROUPING SETS
The GROUPING SETS(expr list) function calculates aggregates for each group of columns inexpr list.
For example, the following query will aggregate the average opening stock price
for these groups:
- Each market sector
- Each stock symbol
- All sectors and symbols
Window
Window functions are available through the use of theOVER clause, which can partition rows into frames. Different
types of functions can be used to aggregate data
over a sliding window.
Parameters
<window function>
<window function>
PARTITION BY
PARTITION BY
PARTITION BY clause is
given, the window function will be calculated over the entire data set.ORDER BY
ORDER BY
FIRST_VALUE() or LAST_VALUE().The ordering expression syntax is:ASC). The default null ordering is NULLS FIRST when
using ascending order and NULLS LAST when using descending order.RANGE. When using ROWS, the frame is applied after any
ordering; so, while several columns may appear in the order expression list,
there will be only one ROWS clause following the list.RANGE
RANGE
ORDER BY clause. All records with this
value within the specified relation to the current record’s value will be used in calculating its
window function result.A range-based frame can be specified for any aggregate function
or the FIRST_VALUE() or LAST_VALUE() ranking function.For a frame between a specified lower bound and the current row:| Frame Bound | Description |
|---|---|
UNBOUNDED PRECEDING | All records in the partition before the one at the upper bound; cannot be used as an upper bound |
<number> PRECEDING | All records in the partition with an ORDER BY value between the current record’s value and <number> less than the current record’s value, inclusive |
CURRENT ROW | The current record being processed by the window function, as well as all peer rows (rows with the same ordering value) |
<number> FOLLOWING | All records in the partition with an ORDER BY value between the current record’s value and <number> more than the current record’s value, inclusive |
UNBOUNDED FOLLOWING | All records in the partition after the one at the lower bound; cannot be used as a lower bound |
ROWS
ROWS
ORDER BY clause. All records within the specified
ordered distance from a given record will be used in calculating its window function value.A row-based frame can be specified for any aggregate function
or the FIRST_VALUE() or LAST_VALUE() ranking function.For a frame between a specified lower bound and the current row:| Frame Bound | Description |
|---|---|
UNBOUNDED PRECEDING | All records in the partition before the one at the upper bound; cannot be used as an upper bound |
<number> PRECEDING | All records in the partition from the one <number> records before the current record through the record at the upper bound |
CURRENT ROW | The current record being processed by the window function |
<number> FOLLOWING | All records in the partition from the record at the lower bound through the one <number> records after the current record |
UNBOUNDED FOLLOWING | All records in the partition after the one at the lower bound; cannot be used as a lower bound |
<alias>
<alias>
Aggregate Functions
AVG(expr)
AVG(expr)
expr over the specified window frameCOUNT(expr)
COUNT(expr)
expr over the specified window frameMAX(expr)
MAX(expr)
expr over the specified window frameMEAN(expr)
MEAN(expr)
AVG(). Calculates the average of the given expression expr over the specified
window frameMIN(expr)
MIN(expr)
expr over the specified window framePRODUCT(expr)
PRODUCT(expr)
expr over the specified window frameRATIO_TO_REPORT(expr)
RATIO_TO_REPORT(expr)
expr to the sum of expr over the specified window
frame. Note that ORDER BY is not supported for this function.STDDEV(expr)
STDDEV(expr)
STDDEV_POP(). Calculates the population standard deviation of the given
expression expr over the specified window frameSTDDEV_POP(expr)
STDDEV_POP(expr)
expr over the specified
window frameSTDDEV_SAMP(expr)
STDDEV_SAMP(expr)
expr over the specified
window frameSUM(expr)
SUM(expr)
expr over the specified window frameVAR(expr)
VAR(expr)
VAR_POP(). Calculates the population variance of the given expression expr over
the specified window frameVAR_POP(expr)
VAR_POP(expr)
expr over the specified window
frameVAR_SAMP(expr)
VAR_SAMP(expr)
expr over the specified window frameRanking Functions
CUME_DIST()
CUME_DIST()
0 (exclusive) to 1 (inclusive). The formula for
this calculation is as follows:COUNT() function in separate partition statements to
arrive at the same result:DENSE_RANK()
DENSE_RANK()
FIRST_VALUE(<column>) [<IGNORE | RESPECT> NULLS]
FIRST_VALUE(<column>) [<IGNORE | RESPECT> NULLS]
IGNORE NULLS or RESPECT NULLS to the function syntax to ignore or respect nulls,
respectively.LAG(<column>[, <num>]) [<IGNORE | RESPECT> NULLS]
LAG(<column>[, <num>]) [<IGNORE | RESPECT> NULLS]
LAG(vendor_id, 3) would list the value in the
vendor_id column from three rows prior to the current row. Optionally, add IGNORE NULLS
or RESPECT NULLS to the function syntax to ignore or respect nulls respectively.LAST_VALUE(<column>) [<IGNORE | RESPECT> NULLS]
LAST_VALUE(<column>) [<IGNORE | RESPECT> NULLS]
IGNORE NULLS or RESPECT NULLS to the function syntax to ignore or respect
nulls respectively.LEAD(<column>[, <num>]) [<IGNORE | RESPECT> NULLS]
LEAD(<column>[, <num>]) [<IGNORE | RESPECT> NULLS]
LEAD(vendor_id, 3) would list the value in the
vendor_id column from three rows after the current row. Optionally, add IGNORE NULLS
or RESPECT NULLS to the function syntax to ignore or respect nulls respectively.NTILE(<num of groups>)
NTILE(<num of groups>)
num of groups groups. For
example, NTILE(4) will partition data by quartiles and return the associated group number,
1 to 4.PERCENT_RANK()
PERCENT_RANK()
0
to 1, inclusive. The formula for this calculation is as follows:RANK() & COUNT() functions in separate partition
statements to arrive at the same result:RANK()
RANK()
ROW_NUMBER()
ROW_NUMBER()
Examples
To calculate the rolling sum of total amounts collected by each taxi vendor over the course of a given day, as well as the number of other trips that occurred within 5 minutes of each trip:PIVOT
ThePIVOT clause can be used to pivot
columns, “rotating” column values into multiple columns (one for each value),
creating wider and shorter denormalized tables from longer, more normalized
tables.
phone_number, which lists each phone number
for a customer as a separate record in the table, a pivot operation can be
performed, creating a single record per customer with the home, work, & cell
phone numbers as separate columns.
With this data:
UNPIVOT
TheUNPIVOT clause can be used to unpivot
columns, “rotating” row values into column values, creating longer, more
normalized tables from shorter, more denormalized tables.
customer_contact, which lists the home,
work, & cell phone numbers for each customer in the table, an unpivot
operation can be performed, creating separate home, work, & cell phone records
for each customer.
With this data:
FROM clause can be eliminated.For example, unpivoting without aliasing the quarterly grade columns will
result in those exact column names being used as the quarter values:Set Operations
There are three types of supported set operations, each having the option of returning duplicate records in the result set by using the keywordALL:
- UNION [ALL] - return all records from both source data sets
- INTERSECT [ALL] - return only records that exist in both source data sets
- EXCEPT [ALL] - return all records that exist in the first data set, but not in the second
UNION
TheUNION set operator creates a single list of records from the results of
two SELECT statements. Use the ALL keyword to keep all records from
both sets; omit it to remove duplicate records and form a single list of records
unique between the two sets. See Limitations and Cautions for limitations.
UNION can be used to return all unique lunch & dinner menu items
together, including items that are the same on both menus, but of a different
price:
price and all columns selected must
match between the two sets for an item to be considered a duplicate,
a lunch item that is priced differently as a dinner item would also
appear in the result set.UNION ALL can be used to return all lunch & dinner menu items together,
including duplicates:
INTERSECT
TheINTERSECT set operator creates a single list of records that exist in
both of the result sets from two SELECT statements. Use the ALL keyword
to keep duplicate records that exist in both sets; omit it to remove duplicate
records and form a single list of records that exist in both sets. See
Limitations for limitations.
INTERSECT can be used to return all lunch menu items (excluding
duplicates) that are also dinner items for the same price:
price and all columns selected must
match between the two sets for an item to be included, a lunch item
that is priced differently as a dinner item would not appear in the
result set.EXCEPT
TheEXCEPT set operator performs set subtraction, creating a single list of
records that exist in the first SELECT statement’s result set, but not in
the second SELECT statement’s result set. Use the ALL keyword to keep
duplicate records that exist in the first set but not in the second; omit it to
remove duplicate records and form a single list of records that exist in the
first set but not the second. See Limitations for limitations:
EXCEPT can be used to return all lunch menu items (excluding
duplicates) that are not also dinner items for the same price:
price and all columns selected must
match between the two sets for an item to be eliminated, a lunch item
that is priced differently as a dinner item would still appear in the
result set.WITH (Common Table Expressions)
TheWITH operation, also known as a Common Table Expression (CTE)
creates a set of data that can be assigned table & column aliases and used one
or more times in subsequent operations. The aliased set can be used within the
SELECT, FROM, or WHERE clauses of a subsequent query or a subsequent
CTE within the same WITH operation.
Parameters
RECURSIVE
RECURSIVE
<cte definition> queries to be self-referential, providing for the
possibility of recursive queries.<cte definition>
<cte definition>
WITH clause, structured as follows:| Parameter | Description |
|---|---|
<cte name> | Table alias given to the data set returned by the CTE. |
<column alias list> | List of aliases assigned to the columns the CTE returns. |
<subquery> | SELECT statement to associate with the corresponding <cte name>. |
<column alias list> is matched to each column returned by the
corresponding <subquery> in the order that each were defined; e.g., for column aliases
(A, B, C) used with a subquery SELECT x, y, z ..., alias A will reference column
x, B will reference y, and C will reference z. If no aliases are used, the
names of the source columns themselves can be used to reference the data set returned by the
subquery.<select statement>
<select statement>
SELECT statement to run with the defined WITH subqueries.WITH statement—no
other column or column alias can be similarly named, for example. Also, when
used in a FROM clause and given a table alias, the table alias must be
preceded with AS.
A CTE can be made available to a DML or DDL statement by having the WITH
statement follow the CREATE TABLE ... AS, INSERT, UPDATE, or
DELETE statement (not precede it).
Examples
To define a simple CTE subquery using aWITH clause:
INSERT statement while using multiple CTE
definitions, follow the INSERT clause with the WITH clause:
Recursive Queries
Common table expressions are used to create recursive queries, via theRECURSIVE option, using the following form:
UNION to remove duplicate records from the result set; use UNION ALL
to return all records from the recursion.
Iteration
Kinetica supports iteration over each record within a data set for the purpose of creating a result set with0 to
N result records per record in the original set.
This iteration can be variable, based on some value within each record, or
fixed, based on a given constant value.
The iteration is performed by joining against the virtual ITER table, as
follows:
<column expression> can be replaced by a constant for fixed iteration.
For example, to extract all of the individual letters from a column of words,
with one record per letter extracted (using variable iteration):
Constants
Each data type has an associated literal constant syntax, which can be used, for instance, to insert constant data values into those columns.Numeric Constants
Integer and floating point data types can be either single-quoted or not.String-Based Constants
String-based data types should be single-quoted.Binary Constants
Binary types can be represented in either of the following forms:- single-quoted or unquoted base-10
- single-quoted hexadecimal
Date/Time Constants
Kinetica accepts unqualified single-quoted date/time values, ANSI SQL, and ODBC escape sequences in the following formats:| Data Type | Native | ANSI | ODBC |
|---|---|---|---|
| Date | 'YYYY-MM-DD' | DATE 'YYYY-MM-DD' | {d 'YYYY-MM-DD'} |
| Time | 'HH:MI:SS.mmm' | TIME 'HH:MI:SS.mmm' | {t 'HH:MI:SS.mmm'} |
| DateTime | 'YYYY-MM-DD[T| ]HH:MI:SS.mmm[Z]' | TIMESTAMP 'YYYY-MM-DD HH:MI:SS.mmm' | {ts 'YYYY-MM-DD HH:MI:SS.mmm'} |
| Timestamp | 'YYYY-MM-DD[T| ]HH:MI:SS.mmm[Z]' | TIMESTAMP 'YYYY-MM-DD HH:MI:SS.mmm' | {ts 'YYYY-MM-DD HH:MI:SS.mmm'} |
Expressions
An expression can consist of a literal constant, a column name, or a function applied to a constant or column name. A compound expression is an operation or function applied to one or more expressions. The following are the supported expression operators:+addition-subtraction*multiplication/division()grouping||string concatenation
Array Functions
Scalar Functions
ARRAY_APPEND(array, value)
ARRAY_APPEND(array, value)
array with value appended to the end.ARRAY_CONCAT(arr1, arr2)
ARRAY_CONCAT(arr1, arr2)
arr1 followed by all of
the elements of array arr2.ARRAY_CONTAINS(array, value)
ARRAY_CONTAINS(array, value)
value is present in array.ARRAY_CONTAINS_ALL(arr1, arr2)
ARRAY_CONTAINS_ALL(arr1, arr2)
arr2 is present in array arr1; otherwise
returns false.ARRAY_CONTAINS_ANY(arr1, arr2)
ARRAY_CONTAINS_ANY(arr1, arr2)
arr2 is present in array arr; otherwise
returns false.ARRAY_DISTINCT(array)
ARRAY_DISTINCT(array)
array values with duplicates removed.ARRAY_EMPTY(array)
ARRAY_EMPTY(array)
array is empty; otherwise returns false.ARRAY_EXCEPT(arr1, arr2)
ARRAY_EXCEPT(arr1, arr2)
arr1 with the ones that
also appear in array arr2 removed.ARRAY_INTERSECT(arr1, arr2)
ARRAY_INTERSECT(arr1, arr2)
arr1 that also appear
in array arr2.ARRAY_ITEM(array, pos)
ARRAY_ITEM(array, pos)
array at the given 1-based pos position.See examples.ARRAY_LENGTH(array)
ARRAY_LENGTH(array)
array at the 1st dimension.See examples.ARRAY_LOWER(array, dim)
ARRAY_LOWER(array, dim)
array in the given dim dimension; since all arrays
are 1-dimensional, only specifying a dimension of 1 will return a value, and since
array indices are 1-based, that value will always be 1.ARRAY_NDIMS(array)
ARRAY_NDIMS(array)
array; since all arrays are
1-dimensional, that number will always be 1.ARRAY_NOT_EMPTY(array)
ARRAY_NOT_EMPTY(array)
array is not empty; otherwise returns false.ARRAY_SLICE(array, from, to)
ARRAY_SLICE(array, from, to)
array between the from index
(inclusive) up to the to index (exclusive) using 0-based indexing. Negative indexes
are treated as offsets from the end of the array.ARRAY_TO_STRING(array, delim)
ARRAY_TO_STRING(array, delim)
array into a string delimited by delim.See examples.ARRAY_UPPER(array, dim)
ARRAY_UPPER(array, dim)
array in the given dim dimension; since all arrays
are 1-dimensional, only specifying a dimension of 1 will return a value, and since
array indices are 1-based, that value will always be equivalent to ARRAY_LENGTH.MAKE_ARRAY(value)
MAKE_ARRAY(value)
value element.STRING_TO_ARRAY(str, delim)
STRING_TO_ARRAY(str, delim)
str, delimited by delim, into an array.See examples.Aggregation/Transposition Functions
The following functions can be used on array columns within aggregations. These functions can be used to convert primitive column values into arrays of those values (aggregation) or to convert array columns into columns of primitive values (unnest).ARRAY_AGG(expr)
ARRAY_AGG(expr)
ARRAY_AGG_DISTINCT(expr)
ARRAY_AGG_DISTINCT(expr)
UNNEST_JSON_ARRAY
UNNEST_JSON_ARRAY
Conditional Functions
Conditional functions are subject to short-circuiting to aid in error-checking.DECODE(expr, match_a, value_a, ..., match_N, value_N[, unmatched_value])
DECODE(expr, match_a, value_a, ..., match_N, value_N[, unmatched_value])
expr: returns the first value whose corresponding match is equal to
expr; returns the optional unmatched_value (or null), if no match is foundIF(expr, value_if_true, value_if_false)
IF(expr, value_if_true, value_if_false)
expr: if true, returns value_if_true; otherwise, if false or null,
returns value_if_false| Parameter | Description |
|---|---|
expr | any true/false condition When an integer column is used directly, this function will interpret non-zero values as true and zero values as false. |
value_if_true | any type; must be the same type as value_if_false |
value_if_false | any type; must be the same type as value_if_true |
CASE
The case statement acts as a scalar function, but has two more complex forms. Note that for each of theseCASE statements, the value expressions must all
be of the same or convertible data type.
In the first form, each WHEN is followed by a conditional expression whose
corresponding THEN expression will have its value returned, if true.
Control will continue through each WHEN until a match is found and the
corresponding value returned; if no match is found, the value of the ELSE
expression will be returned, or null, if no ELSE clause exists.
CASE expression is evaluated. A match of that
result will be attempted against each WHEN expression until a match is found
and the value of the corresponding THEN expression returned; if no match is
found, the value of the ELSE expression will be returned, or null, if no
ELSE clause exists.
Conversion Functions
CAST (expr AS [SQL_]<conv_type>) *or* CONVERT (expr, [SQL_]<conv_type>)
CAST (expr AS [SQL_]<conv_type>) *or* CONVERT (expr, [SQL_]<conv_type>)
expr into conv_type data typeConversion Types:| Numeric | String | Date/Time |
|---|---|---|
BIGINT | CHAR(N) | DATE |
DECIMAL(P,S) | VARCHAR(N) | DATETIME |
DOUBLE | TIME | |
FLOAT | TIMESTAMP | |
INTEGER | TYPE_DATE | |
NUMERIC(P,S) | TYPE_TIME | |
REAL | TYPE_TIMESTAMP | |
SMALLINT | ||
TINYINT | ||
UNSIGNED BIGINT |
SQL_ prefix,
UNSIGNED BIGINT becomes SQL_UNSIGNED_BIGINTCHAR(expr)
CHAR(expr)
exprCHAR1(expr)
CHAR1(expr)
expr to VARCHAR(1) typeCHAR2(expr)
CHAR2(expr)
expr to VARCHAR(2) typeCHAR4(expr)
CHAR4(expr)
expr to VARCHAR(4) typeCHAR8(expr)
CHAR8(expr)
expr to VARCHAR(8) typeCHAR16(expr)
CHAR16(expr)
expr to VARCHAR(16) typeCHAR32(expr)
CHAR32(expr)
expr to VARCHAR(32) typeCHAR64(expr)
CHAR64(expr)
expr to VARCHAR(64) typeCHAR128(expr)
CHAR128(expr)
expr to VARCHAR(128) typeCHAR256(expr)
CHAR256(expr)
expr to VARCHAR(256) typeDATE(expr)
DATE(expr)
expr to date (YYYY-MM-DD) formatDATETIME(expr)
DATETIME(expr)
expr to datetime (YYYY-MM-DD HH24:MI:SS.mmm) formatDECIMAL(expr)
DECIMAL(expr)
expr to DECIMAL typeDOUBLE(expr)
DOUBLE(expr)
expr to DOUBLE typeFLOAT(expr)
FLOAT(expr)
expr to REAL typeINT(expr)
INT(expr)
expr to INTEGER typeLONG(expr)
LONG(expr)
expr to BIGINT type; if expr is a TIMESTAMP or
DATETIME type, the value will be the number of milliseconds since the epochSTRING(expr)
STRING(expr)
expr to a string format appropriate for the expr typeTIME(expr)
TIME(expr)
expr to time (HH24:MI:SS) formatTIMESTAMP(expr)
TIMESTAMP(expr)
expr to TIMESTAMP typeTO_CHAR(expr, format)
TO_CHAR(expr, format)
expr to a string matching the given format.
The returned string will be truncated at 32 characters.
See Date/Time Conversion Codes for the list of format codes.Example:| Function Call | TO_CHAR(DATETIME(971181296000), ‘“Last login: “YYYY-MM-DD’) |
| Return | Last login: 2000-10-10 |
TO_DATE(string, format)
TO_DATE(string, format)
TO_DATETIME(string, format)
TO_DATETIME(string, format)
TO_TIME(string, format)
TO_TIME(string, format)
TO_TIMESTAMP(string, format)
TO_TIMESTAMP(string, format)
ULONG(expr)
ULONG(expr)
expr to UNSIGNED BIGINT typeVECTOR(expr, len)
VECTOR(expr, len)
len number of float values in expr to
VECTOR type.Example:Date/Time Conversion Codes
The following formatting codes can be used to convert date/time strings to native date/time objects (withTO_DATE, TO_DATETIME, TO_TIME and TO_TIMESTAMP)
and for formatting date/time objects as strings (with TO_CHAR).
These characters are interpreted literally: - / , . ; :
Other characters need to be quoted in order to be interpreted literally.
For example, MM-DD-YYYY can be used to convert 01-02-2022 to a date,
while "Today is "MM-DD-YYYY is needed to convert Today is 01-02-2022.
In the following table, Opt in the Input column indicates that the field may be empty
when being read, and still be considered a valid input. This can be useful when reading
data from a source that, for example, sometimes includes milliseconds in their time strings
and sometimes does not (e.g., the MMM code is Opt). Yes in the Input column indicates
that some data must be present in the input string to be considered valid, unless it is after
a $ character, in which case all input after the $ is optional.
| Format Code | Input | Output | Description |
|---|---|---|---|
_ | Yes | Any one character | |
? | Opt | Zero or more non-digit characters | |
$ | Yes | Everything after this is optional; e.g., HH:MI$:SS would accept 12:34 and 12:34:56 | |
AD | Yes | Era indicator without periods | |
A.D. | Yes | Era indicator with periods | |
AM | Yes | Yes | Meridian indicator without periods [AM, PM] |
A.M. | Yes | Yes | Meridian indicator with periods [A.M., P.M.] |
BC | Yes | Era indicator without periods | |
B.C. | Yes | Era indicator with periods | |
C | Yes | Yes | Number of day in calendar month, with optional leading zero [1 - 31] |
CC | Yes | Century (if last 2 digits of the 4-digit year are 00, this is the first 2 digits; otherwise, this is first 2 digits + 1) | |
D | Yes | Yes | Day of week [1 - 7] (Sunday - Saturday) |
DAY | Yes | Yes | Day of week [Sunday - Saturday] |
DD | Yes | Yes | Number of day in month, with leading zero [01 - 31] |
DDD | Yes | Yes | Number of day of year [1 - 366] |
DL | Yes | Yes | Date long format (DAY, MONTH C, RRRR) |
DS | Yes | Yes | Date short format (M/C/RRRR) |
DY | Yes | Yes | Abbreviated day name (e.g., “Mon”) |
FF[1-9] | Opt | Yes | Fractional seconds where the number of fractional second digits can be specified (default is 3 digits); when used for input, the string may contain an optional ”.” preceding the numbers |
H | Yes | Yes | Alias for H12 |
H12 | Yes | Yes | Hour of day in 12-hour format, with optional leading zero [0 - 11] |
H24 | Yes | Yes | Hour of day in 24-hour format, with optional leading zero [0 - 23] |
HH | Yes | Yes | Alias for HH12 |
HH12 | Yes | Yes | Hour of day in 12-hour format, with leading zero [00 - 11] |
HH24 | Yes | Yes | Hour of day in 24-hour format, with leading zero [00 - 23] |
I | Yes | Yes | Last digit of ISO year |
ID | Yes | Yes | ISO 8601 day of week [1 - 7] (Monday - Sunday) |
IDDD | Yes | Yes | ISO 8601 day of year [001 - 371] (where 001 is the Monday of the 1st ISO week) |
IW | Yes | Yes | ISO 8601 week of year [01 - 53] (where 01 contains the first Thursday of the year) |
IY | Yes | Yes | Last 2 digits of ISO year |
IYY | Yes | Yes | Last 3 digits of ISO year |
IYYY | Yes | Yes | Last 4 digits of ISO year |
J | Yes | Yes | Julian day; the number of days since January 1, 4712 BC. Number specified with J must be integers. |
LLL | Opt | Yes | Whole milliseconds (often positioned after a colon); e.g., 12:34:56:78 => 78 milliseconds; when used for input, the string may contain an optional ”.” or ”:” preceding the numbers; when ”.” is found, this code will act like the MMM code |
M | Yes | Yes | Number of month in year, with optional leading zero [1 - 12] |
MI | Yes | Yes | Minute of hour [00 - 59] |
MM | Yes | Yes | Number of month in year, with leading zero [01 - 12] |
MMM | Opt | Yes | Fractions of a second up to milliseconds; e.g., 12:34:56.78 => 780 milliseconds; when used for input, the string may contain an optional ”.” or ”:” preceding the numbers; when ”:” is found, this code will act like the LLL code |
MON | Yes | Yes | 3-character abbreviation of month in title case [Jan - Dec] |
MONTH | Yes | Yes | Full name of month [January - December] |
MS | Opt | Yes | Alias for MMM |
OF | Opt | Yes | Time-zone offset from UTC (TZHTZM) |
PM | Yes | Yes | Alias for AM |
P.M. | Yes | Yes | Alias for A.M. |
Q | Yes | Quarter of the year [1 - 4] (January-March - October-December) | |
RM | Yes | Yes | Roman numeral month [I - XII] (January - December) |
RR | Yes | Yes | Rounded year. Assume the given 2-digit year occurs in the present century, then: * If the assumed date is greater than 50 years into the future, declare the date to be in the previous century * If the assumed date is greater than 50 years into the past, declare the date to be in the next century |
RRRR | Yes | Yes | Either a 2-digit or 4-digit year; if 2-digit, equivalent to RR |
SCC | Yes | Same as CC | |
SS | Yes | Yes | Second of minute [00 - 59] |
SSSS | Yes | Yes | Alias for SSSSS |
SSSSS | Yes | Yes | Seconds past midnight [0 - 86399] |
SYEAR | Yes | Same as YEAR | |
SYYYY | Yes | Yes | Same as YYYY |
TS | Yes | Yes | Time short format (H24:MI:SS.MMM) |
TZ | Opt | Yes | Time zone (TZH) |
TZH | Opt | Yes | Time zone hour (ISO); “Z” or +/- followed by one or two digits (will always output “Z”) |
TZM | Opt | Yes | Time zone minute (ISO); colon followed by one or two digits; for input, an optional colon is allowed at the front; if present, two digits must follow it |
US | Opt | Yes | Microseconds; when used for input, the string may contain an optional ”.” preceding the numbers |
W | Yes | Yes | Week of month [1 - 5], where week 1 starts on the first day of the month and ends on the seventh |
WW | Yes | Yes | Week of year [1 - 53], where week 1 starts on the first day of the year and continues to the seventh day of the year |
X | Yes | Yes | Local radix character (always .. E.g., HH:MI:SSXFF) |
Y | Yes | Yes | Last 1 digit of year |
Y,YYY | Yes | Yes | Year with a comma after the thousands place |
YEAR | Yes | Year spelled out (e.g., “Two Thousand Twenty Five”) | |
YY | Yes | Yes | Last 2 digits of year |
YYY | Yes | Yes | Last 3 digits of year |
YYYY | Yes | Yes | 4-digit year |
Date/Time Functions
This section comprises the following functions:- Date/Time Base Functions, which can extract parts of date/time expressions, convert back and forth between data types, and return the current date/time
- Date/Time Complex Conversion Functions, which can perform more complex date/type conversions
Date/Time Base Functions
CLOCK_TIMESTAMP()
CLOCK_TIMESTAMP()
YYYY-MM-DD HH24:MI:SS.mmmCLOCK_TIMESTAMP may return different values each time it is called in the
same query or SQL Procedure, which may lead to data getting out of sync across HA
clusters. Use CURRENT_DATETIME to avoid this issue.CURRENT_DATE()
CURRENT_DATE()
YYYY-MM-DDCURRENT_DATETIME()
CURRENT_DATETIME()
YYYY-MM-DD HH24:MI:SS.mmmCURRENT_DATETIME will return same values each time it is called in the
same query or SQL Procedure, and should keep data in-sync across HA clusters.
See CLOCK_TIMESTAMP to always get the actual time each time it is called.CURRENT_TIME()
CURRENT_TIME()
HH24:MI:SS.mmmCURRENT_TIMESTAMP()
CURRENT_TIMESTAMP()
YYYY-MM-DD HH24:MI:SS.mmm; to
return the date & time as the number of milliseconds since the
epoch, pass the result of this function to LONG()DATEADD (unit, amount, expr)
DATEADD (unit, amount, expr)
amount of unit date/time intervals to the date/time in
exprThe following date/time intervals are supported for unit:| Constant | Description |
|---|---|
YEAR | Year is modified by interval amount (not affected by leap year, etc.) |
QUARTER | Month is modified by three times the interval amount, irrespective of the number of days in the months between; day adjusting performed the same as the MONTH description, but only on final month (e.g., Jan 31st + 1 quarter will be Apr 30th, not Apr 28th because of February) |
MONTH | Month is modified by interval amount and date adjusted if overflow/underflow occurs; day adjusted to last day of calculated month if not a valid day for that month (e.g. Apr 31st -> Apr 30th) |
WEEK | Day is modified by 7 times the interval amount (time not affected by daylight savings time, etc.); month & year are adjusted, if overflow/underflow occurs |
DAY | Day is modified by interval amount (time not affected by daylight savings time, etc.); date is adjusted, if overflow/underflow occurs |
HOUR | Hour is modified by interval amount (time not affected by daylight savings time, etc.); date is adjusted, if overflow/underflow occurs |
MINUTE | Minute is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
SECOND | Second is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
MILLISECOND | Millisecond is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
FRAC_SECOND | Nanosecond is modified by interval amount; date/time are adjusted, if overflow/underflow occurs Time is processed to millisecond precision, so any portion of an amount with finer granularity than 1,000,000 nanoseconds will be ignored (e.g., requesting the addition of 1,234,567 nanoseconds will result in 1 millisecond actually being added) |
unit types can have a SQL_TSI_ prefix prepended to them; e.g., both
DAY and SQL_TSI_DAY are valid unit types for specifying a day interval.| Function Call | Result |
|---|---|
DATEADD(YEAR, 1, ‘2000-10-10’) | 2001-10-10 |
DATEADD(QUARTER, 1, ‘2000-11-30’) | 2001-02-28 |
DATEADD(MONTH, 1, ‘2000-01-31’) | 2000-02-29 |
DATEADD(WEEK, 53, ‘2000-01-01’) | 2001-01-06 |
DATEADD(DAY, 1, ‘2000-12-31’) | 2001-01-01 |
DATEADD(HOUR, 12, ‘2000-10-10 12:34:56’) | 2000-10-11 00:34:56.000 |
DATEADD(MINUTE, 1, ‘2000-10-10 12:34:56’) | 2000-10-10 12:35:56.000 |
DATEADD(SECOND, 1, ‘2000-12-31 23:59:59’) | 2001-01-01 00:00:00.000 |
DATEADD(MILLISECOND, 1, ‘2000-10-10 12:34:56’) | 2000-10-10 12:34:56.001 |
DATEADD(FRAC_SECOND, 1000000, ‘2000-10-10 12:34:56’) | 2000-10-10 12:34:56.001 |
DATEADD(SECOND, 1, TIME ‘12:34:56’) | 12:34:57.000 |
DATE_BUCKET (width, ds[, offset[, base]])
DATE_BUCKET (width, ds[, offset[, base]])
ds falls, based on a set of fixed-width “buckets”
with the given width, start-aligned base date, and offset from that base date.The width is the number of days each bucket should span.The offset is the number of days after (positive offset) or number of days before (negative
offset) the base date to which the buckets should be aligned. The default is no offset.The default base is 2000-01-03.Typically, DATE_BUCKET is used in the following type of query:- Dates in the
dscolumn of theexample.host_metrics_summarytable will be grouped into buckets - Each bucket will span a range of
7days - The baseline bucket will start at
2023-02-18(2023-02-21offset by-3days) and continue through2023-02-24(7days, including2023-02-18) - Buckets will extend before & after the baseline bucket in contiguous, non-overlapping fashion
- Each result record will show the date in the middle of the bucket’s date range (
+ INTERVAL 3 DAYSfrom the start of each7day span) and the average CPU usage across the records contained within that date range - Gaps in the data will not be filled in with empty buckets—only buckets containing the dates found in
the
dscolumn ofexample.host_metrics_summarywill be returned in the result set
DATEDIFF ([unit,] begin, end)
DATEDIFF ([unit,] begin, end)
unit need to be added to (or subtracted from) begin to equal
end (or get as close as possible without going past it) using the unit types and
and rules specified in DATEADD.The default unit is DAY.DATEADD in all cases, as adding 1
MONTH to Mar 31st results in Apr 30th, but the DATEDIFF in MONTH
units between those two dates is 0.| Function Call | Result |
|---|---|
DATEDIFF(DATE(‘2000-10-10’), DATE(‘2000-12-31’)) | 82 |
DATEDIFF(DATE(‘2000-03-31’), DATE(‘2000-04-30’)) | 30 |
DATEDIFF(DATE(‘2000-12-31’), DATE(‘2000-10-10’)) | -82 |
DATEDIFF(DATETIME(‘2000-10-10 12:34:56’), 978222896000) | 81 |
DATEDIFF(MONTH, DATE(‘2000-10-10’), DATE(‘2000-12-31’)) | 2 |
DATEDIFF(MONTH, DATE(‘2000-03-31’), DATE(‘2000-04-30’)) | 0 |
DATEDIFF(MONTH, DATE(‘2000-12-31’), DATE(‘2000-10-10’)) | -2 |
DATEDIFF(HOUR, DATETIME(‘2000-10-10 12:34:56’), 978222896000) | 1956 |
DATEPART(part, expr)
DATEPART(part, expr)
part of the date/time expr. The part may be any of
those specified in DATE_TRUNC(part, expr), plus the following:| Constant | Description |
|---|---|
SECS_SINCE_EPOCH | Return the number of seconds since the epoch (1970-01-01). |
MSECS_SINCE_EPOCH | Return the number of milliseconds since the epoch. |
| Function Call | Result |
|---|---|
DATEPART(YEAR, ‘2000-12-31’) | 2000 |
DATEPART(MONTH, ‘2000-03-31 12:34:56.000’) | 3 |
DATEPART(DAY, ‘2000-03-31 12:34:56.000’) | 31 |
DATEPART(SECOND, ‘2000-03-31 12:34:56.220’) | 56 |
DATEPART(MSECS_SINCE_EPOCH, ‘2000-03-31 12:34:56.220’) | 954506096220 |
DATE_TRUNC(part, expr)
DATE_TRUNC(part, expr)
expr after truncating it beyond the given date/time part.
The following date/time constants are supported for part:| Constant | Description |
|---|---|
YEAR | Return the first day of the year in which expr occurs |
QUARTER | Return the first day of the quarter in which expr occurs |
MONTH | Return the first day of the month in which expr occurs |
WEEK | Return the first day of the week in which expr occurs |
DAY | Return the date (at midnight) on which expr occurs |
HOUR | Return the timestamp up to the hour in which expr occurs |
MINUTE | Return the timestamp up to the minute in which expr occurs |
SECOND | Return the timestamp up to the second in which expr occurs |
MILLISECOND | Return the timestamp up to the millisecond in which expr occurs |
| Function Call | Result |
|---|---|
DATE_TRUNC(YEAR, ‘2008-09-10 12:34:56.789’) | 2008-01-01 00:00:00.000 |
DATE_TRUNC(QUARTER, ‘2008-09-10 12:34:56.789’) | 2008-07-01 00:00:00.000 |
DATE_TRUNC(MONTH, ‘2008-09-10 12:34:56.789’) | 2008-09-01 00:00:00.000 |
DATE_TRUNC(WEEK, ‘2008-09-10 12:34:56.789’) | 2008-09-07 00:00:00.000 |
DATE_TRUNC(DAY, ‘2008-09-10 12:34:56.789’) | 2008-09-10 00:00:00.000 |
DATE_TRUNC(HOUR, ‘2008-09-10 12:34:56.789’) | 2008-09-10 12:00:00.000 |
DATE_TRUNC(MINUTE, ‘2008-09-10 12:34:56.789’) | 2008-09-10 12:34:00.000 |
DATE_TRUNC(SECOND, ‘2008-09-10 12:34:56.789’) | 2008-09-10 12:34:56.000 |
DATE_TRUNC(MILLISECOND, ‘2008-09-10 12:34:56.789’) | 2008-09-10 12:34:56.789 |
DAY(expr)
DAY(expr)
DAYOFMONTH(expr)DAYNAME(expr)
DAYNAME(expr)
expr and converts it to the
corresponding day name [Sunday - Saturday ]DAYOFMONTH(expr)
DAYOFMONTH(expr)
expr [1 - 31]DAYOFWEEK(expr)
DAYOFWEEK(expr)
expr [1 - 7]| Expression Value | Result |
|---|---|
| Date on Sunday | 1 |
| Date on Monday | 2 |
| Date on Tuesday | 3 |
| Date on Wednesday | 4 |
| Date on Thursday | 5 |
| Date on Friday | 6 |
| Date on Saturday | 7 |
DAY_OF_WEEK(expr)
DAY_OF_WEEK(expr)
DAYOFWEEK(expr)DAYOFYEAR(expr)
DAYOFYEAR(expr)
expr [1 - 366]DAY_OF_YEAR(expr)
DAY_OF_YEAR(expr)
DAYOFYEAR(expr)EPOCH_MSECS_TO_DATETIME(expr)
EPOCH_MSECS_TO_DATETIME(expr)
expr milliseconds since the epoch to a date/timeExample:| Function Call | EPOCH_MSECS_TO_DATETIME(971181296789) |
| Return | 2000-10-10 12:34:56.789 |
EPOCH_SECS_TO_DATETIME(expr)
EPOCH_SECS_TO_DATETIME(expr)
expr seconds since the epoch to a date/timeExample:| Function Call | EPOCH_SECS_TO_DATETIME(971181296) |
| Return | 2000-10-10 12:34:56.000 |
EXTRACT(<part> FROM <expr>)
EXTRACT(<part> FROM <expr>)
part from the date/time expr. This function is used to support database
clients which require the call in this form; however, each of the supported date/time part
constants results in a call for which there is a simpler, more direct corresponding call, which are
listed below.| Constant | Corresponding Alternative Function Call |
|---|---|
YEAR | YEAR(expr) |
QUARTER | QUARTER(expr) |
MONTH | MONTH(expr) |
WEEK | WEEK(expr) |
DAY | DAY(expr) |
HOUR | HOUR(expr) |
MINUTE | MINUTE(expr) |
SECOND | SECOND(expr) |
MILLISECOND | MSEC(expr) |
EPOCH | SECS_SINCE_EPOCH(expr) |
HOUR(expr)
HOUR(expr)
expr [0 - 23]<expr> + INTERVAL '<amount>' <part> <expr> - INTERVAL '<amount>' <part>
<expr> + INTERVAL '<amount>' <part> <expr> - INTERVAL '<amount>' <part>
expr the integral
amount units of type part. This mirrors the behavior of
the TIMESTAMPADD function, only with a different format and
different date/time part constants. The following date/time
constants are supported for part:| Constant | Description |
|---|---|
YEAR | Year is modified by interval amount (not affected by leap year, etc.) |
QUARTER | Month is modified by three times the interval amount, irrespective of the number of days in the months between; day adjusting performed the same as the MONTH description, but only on final month (e.g., Jan 31st + 1 quarter will be Apr 30th, not Apr 28th because of February) |
MONTH | Month is modified by interval amount and date adjusted if overflow/underflow occurs; day adjusted to last day of calculated month if not a valid day for that month (e.g. Apr 31st -> Apr 30th) |
WEEK | Day is modified by 7 times the interval amount (time not affected by daylight savings time, etc.); month & year are adjusted, if overflow/underflow occurs |
DAY | Day is modified by interval amount (time not affected by daylight savings time, etc.); date is adjusted, if overflow/underflow occurs |
HOUR | Hour is modified by interval amount (time not affected by daylight savings time, etc.); date is adjusted, if overflow/underflow occurs |
MINUTE | Minute is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
SECOND | Second is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
LAST_DAY(date)
LAST_DAY(date)
dateMINUTE(expr)
MINUTE(expr)
expr [0 - 59]MONTH(expr)
MONTH(expr)
expr [1 - 12]MONTHNAME(expr)
MONTHNAME(expr)
expr and converts it to
the corresponding month name [January - December]MSEC(expr)
MSEC(expr)
expr [0 - 999]MSECS_SINCE_EPOCH(expr)
MSECS_SINCE_EPOCH(expr)
expr date/time to the number of milliseconds since the epochExample:| Function Call | MSECS_SINCE_EPOCH(‘2000-10-10 12:34:56.789’) |
| Return | 971181296789 |
NEXT_DAY(date, day_of_week)
NEXT_DAY(date, day_of_week)
day_of_week, that occurs after the given dateSome examples, given that 2000-10-10 is a Tuesday:| Function Call | Result |
|---|---|
NEXT_DAY(‘2000-10-10’, ‘Wednesday’) | 2000-10-11 |
NEXT_DAY(‘2000-10-10’, ‘Friday’) | 2000-10-13 |
NEXT_DAY(‘2000-10-10’, ‘Tuesday’) | 2000-10-17 |
NOW()
NOW()
CURRENT_DATETIME()QUARTER(expr)
QUARTER(expr)
expr [1 - 4]| Expression Value | Result |
|---|---|
| Date in January, February, or March | 1 |
| Date in April, May, or June | 2 |
| Date in July, August, or September | 3 |
| Date in October, November, or December | 4 |
SECOND(expr)
SECOND(expr)
expr [0 - 59]SEC(expr)
SEC(expr)
SECOND(expr)SECS_SINCE_EPOCH(expr)
SECS_SINCE_EPOCH(expr)
expr date/time to the number of seconds since the epochExample:| Function Call | SECS_SINCE_EPOCH(‘2000-10-10 12:34:56’) |
| Return | 971181296 |
SLEEP(expr)
SLEEP(expr)
expr seconds; though system load may delay the return from this call
for longer than the specified amount. Use a decimal for expr to pause for less than a second;
e.g., SLEEP(0.001) will pause for at least 1 millisecond. SLEEP should be invoked in a
Tableless Query to avoid being called for every record in a result set; e.g.:TIME_BUCKET (width, ts[, offset[, base]])
TIME_BUCKET (width, ts[, offset[, base]])
ts falls, based on a set of fixed-width
“buckets” with the given width, start-aligned base date/time, and offset from that base
date/timeThe width is the number of milliseconds each bucket should span. An INTERVAL can also be used
to specify the width.The offset is the number of milliseconds after (positive offset) or number of milliseconds
before (negative offset) the base date/time to which the buckets should be aligned. An
INTERVAL can also be used to specify the offset. The default is no offset.The default base is 2000-01-03 00:00:00.Typically, TIME_BUCKET is used in the following type of query:- Timestamps in the
tscolumn of theexample.host_metricstable will be grouped into buckets - Each bucket will span a
5minute interval - The baseline bucket will start at
2023-02-27 23:57:30(2023-02-28offset by-2.5minutes) and continue through2023-02-28 00:02:30(5minutes from2023-02-27 23:57:30) - Buckets will extend before & after the baseline bucket in contiguous, non-overlapping fashion
- Each result record will show the timestamp in the middle of the bucket’s range
(
+ INTERVAL 2.5 MINUTESfrom the start of each5minute span) and the average CPU usage across the records contained within that date/time range - Gaps in the data will not be filled in with empty buckets—only buckets containing the timestamps
found in the
tscolumn ofexample.host_metricswill be returned in the result set
TIMESTAMPADD (unit, amount, expr)
TIMESTAMPADD (unit, amount, expr)
amount of unit date/time intervals to the date/time in
exprThe following date/time intervals are supported for unit:| Constant | Description |
|---|---|
YEAR | Year is modified by interval amount (not affected by leap year, etc.) |
QUARTER | Month is modified by three times the interval amount, irrespective of the number of days in the months between; day adjusting performed the same as the MONTH description, but only on final month (e.g., Jan 31st + 1 quarter will be Apr 30th, not Apr 28th because of February) |
MONTH | Month is modified by interval amount and date adjusted if overflow/underflow occurs; day adjusted to last day of calculated month if not a valid day for that month (e.g. Apr 31st -> Apr 30th) |
WEEK | Day is modified by 7 times the interval amount (time not affected by daylight savings time, etc.); month & year are adjusted, if overflow/underflow occurs |
DAY | Day is modified by interval amount (time not affected by daylight savings time, etc.); date is adjusted, if overflow/underflow occurs |
HOUR | Hour is modified by interval amount (time not affected by daylight savings time, etc.); date is adjusted, if overflow/underflow occurs |
MINUTE | Minute is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
SECOND | Second is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
MILLISECOND | Millisecond is modified by interval amount; date/time are adjusted, if overflow/underflow occurs |
FRAC_SECOND | Nanosecond is modified by interval amount; date/time are adjusted, if overflow/underflow occurs Time is processed to millisecond precision, so any portion of an amount with finer granularity than 1,000,000 nanoseconds will be ignored (e.g., requesting the addition of 1,234,567 nanoseconds will result in 1 millisecond actually being added) |
unit types can have a SQL_TSI_ prefix prepended to them; e.g., both
DAY and SQL_TSI_DAY are valid unit types for specifying a day interval.| Function Call | Result |
|---|---|
TIMESTAMPADD(SQL_TSI_YEAR, 1, ‘2000-10-10’) | 2001-10-10 |
TIMESTAMPADD(SQL_TSI_QUARTER, 1, ‘2000-11-30’) | 2001-02-28 |
TIMESTAMPADD(SQL_TSI_MONTH, 1, ‘2000-01-31’) | 2000-02-29 |
TIMESTAMPADD(SQL_TSI_WEEK, 53, ‘2000-01-01’) | 2001-01-06 |
TIMESTAMPADD(SQL_TSI_DAY, 1, ‘2000-12-31’) | 2001-01-01 |
TIMESTAMPADD(SQL_TSI_HOUR, 12, ‘2000-10-10 12:34:56’) | 2000-10-11 00:34:56.000 |
TIMESTAMPADD(SQL_TSI_MINUTE, 1, ‘2000-10-10 12:34:56’) | 2000-10-10 12:35:56.000 |
TIMESTAMPADD(SQL_TSI_SECOND, 1, ‘2000-12-31 23:59:59’) | 2001-01-01 00:00:00.000 |
TIMESTAMPADD(SQL_TSI_MILLISECOND, 1, ‘2000-10-10 12:34:56’) | 2000-10-10 12:34:56.001 |
TIMESTAMPADD(SQL_TSI_FRAC_SECOND, 1000000, ‘2000-10-10 12:34:56’) | 2000-10-10 12:34:56.001 |
TIMESTAMPADD(SQL_TSI_SECOND, 1, TIME ‘12:34:56’) | 12:34:57.000 |
TIMESTAMPDIFF (unit, begin, end)
TIMESTAMPDIFF (unit, begin, end)
unit need to be added to (or subtracted from) begin to equal
end (or get as close as possible without going past it) using the unit types and
and rules specified in TIMESTAMPADD.TIMESTAMPADD in all cases, as adding 1
MONTH to Mar 31st results in Apr 30th, but the TIMESTAMPDIFF in MONTH
units between those two dates is 0.| Function Call | Result |
|---|---|
TIMESTAMPDIFF(MONTH, DATETIME(‘2000-10-10 01:23:45.678’), DATETIME(‘2000-12-31 12:34:56.789’)) | 2 |
TIMESTAMPDIFF(MONTH, DATETIME(‘2000-03-31 01:23:45.678’), DATETIME(‘2000-04-30 12:34:56.789’)) | 0 |
TIMESTAMPDIFF(MONTH, DATETIME(‘2000-12-31 01:23:45.678’), DATETIME(‘2000-10-10 12:34:56.789’)) | -2 |
TIMESTAMPDIFF(HOUR, DATETIME(‘2000-10-10 12:34:56.789’), TIMESTAMP(978222896678)) | 1955 |
TIMESTAMP_TRUNC(part, expr)
TIMESTAMP_TRUNC(part, expr)
DATE_TRUNC(part, expr)UNIX_TIMESTAMP(expr)
UNIX_TIMESTAMP(expr)
SECS_SINCE_EPOCH(expr)WEEK(expr)
WEEK(expr)
expr [1 - 54]; each full week starts on
Sunday (a 1 is returned for the week containing Jan 1st)YEAR(expr)
YEAR(expr)
expr; 4-digit year, A.D.Date/Time Complex Conversion Functions
DATE_TO_EPOCH_MSECS(year, month, day, hour, min, sec, msec)
DATE_TO_EPOCH_MSECS(year, month, day, hour, min, sec, msec)
| Function Call | DATE_TO_EPOCH_MSECS(2017, 06, 15, 09, 22, 15, 42) |
| Return | 1497518535042 |
| Resolves To | Thursday, June 15, 2017 9:22:15.042 AM |
DATE_TO_EPOCH_SECS(year, month, day, hour, min, sec)
DATE_TO_EPOCH_SECS(year, month, day, hour, min, sec)
| Function Call | DATE_TO_EPOCH_SECS(2017, 06, 15, 09, 22, 15) |
| Return | 1494926535 |
| Resolves To | Thursday, June 15, 2017 9:22:15.042 AM |
TIMESTAMP_FROM_DATE_TIME(date, time)
TIMESTAMP_FROM_DATE_TIME(date, time)
| Function Call | TIMESTAMP_FROM_DATE_TIME(‘2017-06-15’, ‘10:37:30’) |
| Return | 2017-06-15 10:37:30.000 |
WEEK_TO_EPOCH_MSECS(year, week_number)
WEEK_TO_EPOCH_MSECS(year, week_number)
| Function Call | WEEK_TO_EPOCH_MSECS(2017,-32) |
| Return | 1463270400000 |
| Resolves To | Sunday, May 15, 2016 12:00:00 AM |
WEEK_TO_EPOCH_SECS(year, week_number)
WEEK_TO_EPOCH_SECS(year, week_number)
| Function Call | WEEK_TO_EPOCH_SECS(2017,-32) |
| Return | 1463270400 |
| Resolves To | Sunday, May 15, 2016 12:00:00 AM |
Geospatial/Geometry Functions
Five types of geospatial functions are available in Kinetica:- Scalar Functions - apply a geospatial function at the record level to WKT or X/Y data
- Enhanced Performance Scalar Functions - apply performance-optimized geospatial functions to X/Y data
- Aggregate Functions - apply a geospatial function across groups of records to WKT or X/Y data
- Track Functions - apply scalar & aggregate functions to track-based data
- H3 Functions - apply H3 gridding functions to WKT or X/Y data
Enhanced Performance Scalar Functions
The functions below all comparex and y coordinates to geometry objects
(or vice versa), thus increasing their performance in queries. Each of these
functions have a geometry-to-geometry version listed in the next section.
STXY_CONTAINS(geom, x, y)
STXY_CONTAINS(geom, x, y)
1 (true) if geom contains the x and y coordinate, e.g. lies in the interior
of geom. The coordinate cannot be on the boundary and also be contained because geom does not
contain its boundarySTXY_CONTAINSPROPERLY(geom, x, y)
STXY_CONTAINSPROPERLY(geom, x, y)
1 (true) if the x and y coordinate intersects the interior of geom but not
the boundary (or exterior) because geom does not contain its boundary but does contain itselfSTXY_COVEREDBY(x, y, geom)
STXY_COVEREDBY(x, y, geom)
1 (true) if the x and y coordinate is covered by geomSTXY_COVERS(geom, x, y)
STXY_COVERS(geom, x, y)
1 (true) if geom covers the x and y coordinateSTXY_DISJOINT(x, y, geom)
STXY_DISJOINT(x, y, geom)
1 (true) if the given x and y coordinate and the geometry geom do not
spatially intersect.STXY_DISTANCE (x, y, geom[, solution])
STXY_DISTANCE (x, y, geom[, solution])
x and y coordinate and geom using the
specified solution type. Solution types available:0(default) - Euclidean; returns 2-D Euclidean distance1- Haversine; returns minimum sphere distance in meters2- Vincenty; returns minimum spheroid distance in meters, more accurate than Haversine but slower performance
x and y coordinate and geom intersect (verify using ST_INTERSECTS),
the distance will always be 0.STXY_DWITHIN (x, y, geom, distance[, solution])
STXY_DWITHIN (x, y, geom, distance[, solution])
1 (true) if the x and y coordinate is within the specified distance from
geom using the specified solution type. Solution types available:0(default) - Euclidean; uses degrees to calculate distance1- Sphere; uses meters to calculate sphere distance2- Spheroid; uses meters to calculate spheroid distance
STXY_ENVDWITHIN (x, y, geom, distance[, solution])
STXY_ENVDWITHIN (x, y, geom, distance[, solution])
1 (true) if the x and y coordinate is within the specified distance from the
bounding box of geom using the specified solution type. Solution types available:0(default) - Euclidean; uses degrees to calculate distance1- Sphere; uses meters to calculate distance
STXY_ENVINTERSECTS(x, y, geom)
STXY_ENVINTERSECTS(x, y, geom)
1 (true) if the bounding box of the given geometry geom intersects the x and
y coordinate.STXY_GEOHASH(x, y[, precision])
STXY_GEOHASH(x, y[, precision])
x and y coordinates with specified
precision (the length of the resulting geohash string). The longer the precision, the more
precise the hash is. By default, precision is set to 20; the max for precision is 32.See Geohash for an example.STXY_H3(x, y, resolution)
STXY_H3(x, y, resolution)
H3_XYTOCELL; see H3 Functions.STXY_INTERSECTION(x, y, geom)
STXY_INTERSECTION(x, y, geom)
x and y coordinate and the given geometry geom,
i.e. the point itself.STXY_INTERSECTS(x, y, geom)
STXY_INTERSECTS(x, y, geom)
1 (true) if the x and y coordinate and geom intersect in 2-D.STXY_TOUCHES(x, y, geom)
STXY_TOUCHES(x, y, geom)
1 (true) if the x and y coordinate and geometry geom have at least one point
in common but their interiors do not intersect. If geom is a GEOMETRYCOLLECTION, a 0 is
returned regardless if the point and geometry touchSTXY_WITHIN(x, y, geom)
STXY_WITHIN(x, y, geom)
1 (true) if the x and y coordinate is completely inside the geom geometry
i.e., not on the boundaryScalar Functions
DIST(x1, y1, x2, y2)
DIST(x1, y1, x2, y2)
SQRT( (x1-x2)*(x1-x2) + (y1-y2)*(y1-y2) ).GEODIST(lon1, lat1, lon2, lat2)
GEODIST(lon1, lat1, lon2, lat2)
GEOHASH_DECODE_LATITUDE(geohash)
GEOHASH_DECODE_LATITUDE(geohash)
geohash and returns the latitude value for the given hash string. Supports a
maximum geohash character length of 16.GEOHASH_DECODE_LONGITUDE(geohash)
GEOHASH_DECODE_LONGITUDE(geohash)
geohash and returns the longitude value for the given hash string. Supports a
maximum geohash character length of 16.GEOHASH_ENCODE(lat, lon, precision)
GEOHASH_ENCODE(lat, lon, precision)
precision. The maximum precision is 15.GEOMETRY(wkt)
GEOMETRY(wkt)
ST_GEOMFROMTEXT(wkt)ST_ADDPOINT (linestring, point[, position])
ST_ADDPOINT (linestring, point[, position])
point geometry to the given linestring geometry at the specified
position, which is a 0-based index. If no position is specified, the point will be added to the end.ST_ALMOSTEQUALS (geom1, geom2[, decimal])
ST_ALMOSTEQUALS (geom1, geom2[, decimal])
1 (true) if given geometries, geom1 and geom2, are almost spatially equal within
the given amount of decimal scale. Note that geometries will still be considered equal if the
decimal scale for the geometries is within a half order of magnitude of each other; e.g., if
decimal is set to 2, then POINT(63.4 123.45) and POINT(63.4 123.454) are equal, but
POINT(63.4 123.45) and POINT(63.4 123.459) are not equal. The geometry types must match to be
considered equal.If no decimal scale is specified, a default scale of 6 will be applied.ST_AREA(geom[, solution])
ST_AREA(geom[, solution])
geom if it is a POLYGON or MULTIPOLYGON using the
specified solution type. Returns 0 if the input geometry type is (MULTI)POINT or
(MULTI)LINESTRING. Solution types available:0(default) - 2D Euclidean area1- curved surface area on a sphere in square meters2- curved surface area on a spheroid in square meters
ST_AZIMUTH(geom1, geom2)
ST_AZIMUTH(geom1, geom2)
geom1 and geom2.
Returns a null if the input geometry type is MULTIPOINT, (MULTI)LINESTRING, or (MULTI)POLYGON.ST_BOUNDARY(geom)
ST_BOUNDARY(geom)
geom. Returns an empty
geometry if geom is an empty geometry. Returns a null if geom is a GEOMETRYCOLLECTIONST_BOUNDINGDIAGONAL(geom)
ST_BOUNDINGDIAGONAL(geom)
geom) bounding box.ST_BUFFER (geom, radius[, style[, solution]])
ST_BUFFER (geom, radius[, style[, solution]])
geom is
less than or equal to the given distance radius. The radius units can be specified by the
solution type (default is in degrees) and the radius is created in the provided style.
The style options are specified as a list of blank-separated key-value pairs, e.g.,
'quad_segs=8 endcap=round'. If an empty style list ('') is provided, the default settings
will be used. The style parameter must be specified to provide a solution type.Available style options:quad_segs- the number of segments used to approximate a quarter circle (default is8)endcap- the endcap style of the buffer (default isround); options areround,flat(orbutt), andsquarejoin- the join style of the buffer (default isround); options areround,mitre(ormiter), andbevelmitre_limit- the mitre ratio limit expressed as a floating-point number (miter_limitis also acceptable)
solution types:0(default) - 2D Euclidean radius distance in degrees1- curved surface radius distance on a sphere in meters2- curved surface radius distance on a spheroid in meters
ST_BUFFERBYCOMPONENT (geom, radius[, style[, solution]])
ST_BUFFERBYCOMPONENT (geom, radius[, style[, solution]])
ST_BUFFER using the same parameters. The only
difference is the buffered geometry is calculated by independently buffering each individual component
and then the buffered components are dissolved (i.e. unioned) together to produce the final output. This
can produce very similar (but not identical) results to ST_BUFFER but will often run much faster.ST_CENTROID(geom)
ST_CENTROID(geom)
geom as a POINT. For (MULTI)POINTs, the center is
calculated as the average of the input coordinates. For (MULTI)LINESTRINGs, the center is calculated
as the weighted length of each given LINESTRING. For (MULTI)POLYGONs, the center is calculated as
the weighted area of each given POLYGON. If geom is an empty geometry, an empty
GEOMETRYCOLLECTION is returnedST_CLIP(geom1, geom2)
ST_CLIP(geom1, geom2)
geom1 and geom2ST_CLOSESTPOINT (geom1, geom2[, solution])
ST_CLOSESTPOINT (geom1, geom2[, solution])
POINT in geom1 that is closest to geom2 using the specified solution
type. If geom1 or geom2 is empty, a null is returned. Solution types available:0(default) - Euclidean; calculates the closest point using 2-D Euclidean distance1- Haversine; calculates the closest point using sphere distance in meters2- Vincenty; returns minimum spheroid distance in meters, more accurate than Haversine but slower performance
ST_COLLECT(geom1, geom2)
ST_COLLECT(geom1, geom2)
geom1 and geom2. If geom1 and geom2
are the same, singular geometry type, a MULTI* is returned, e.g., if geom1 and geom2 are both
POINTs (empty or no), a MULTIPOINT is returned. If geom1 and geom2 are neither the same type
nor singular geometries, a GEOMETRYCOLLECTION is returned.ST_COLLECTIONEXTRACT (collection, type)
ST_COLLECTIONEXTRACT (collection, type)
type from the given geometry collection. Type is a number that
maps to the following:1=POINT2=LINESTRING3=POLYGON
ST_COLLECTIONHOMOGENIZE(collection)
ST_COLLECTIONHOMOGENIZE(collection)
collection, e.g., a collection with a single POINT will
be returned as POINT(x y), and a collection with multiple individual points will be returned as a
MULTIPOINT.ST_CONCAVEHULL (geom, target_percent[, allow_holes])
ST_CONCAVEHULL (geom, target_percent[, allow_holes])
geom set.
Use target_percent (values between 0 and 1) to determine the percent of area of a convex hull the
concave hull will attempt to fill; 1 will return the same geometry as an ST_CONVEXHULL
operation. Set allow_holes to 1 (true) to allow holes in the resulting geometry; default
value is 0 (false). Note that allow_holes is independent of the area of target_percent.ST_CONTAINS(geom1, geom2)
ST_CONTAINS(geom1, geom2)
1 (true) if no points of geom2 lie in the exterior of geom1 and at least one
point of geom2 lies in the interior of geom1. Note that geom1 does not contain its
boundary but does contain itself.ST_CONTAINSPROPERLY(geom1, geom2)
ST_CONTAINSPROPERLY(geom1, geom2)
1 (true) if geom2 intersects the interior of geom1 but not the boundary
(or exterior). Note that geom1 does not contain its boundary but does contain itself.ST_CONVEXHULL(geom)
ST_CONVEXHULL(geom)
geom set.ST_COORDDIM(geom)
ST_COORDDIM(geom)
geom, e.g., a geometry with x, y, and z
coordinates would return 3.ST_COVEREDBY(geom1, geom2)
ST_COVEREDBY(geom1, geom2)
1 (true) if no point in geom1 is outside geom2.ST_COVERS(geom1, geom2)
ST_COVERS(geom1, geom2)
1 (true) if no point in geom2 is outside geom1.ST_CROSSES(geom1, geom2)
ST_CROSSES(geom1, geom2)
1 (true) if the given geometries, geom1 and geom2, spatially cross, meaning some
but not all interior points in common. If geom1 and/or geom2 are a GEOMETRYCOLLECTION, a
0 is returned regardless of if the two geometries crossST_DIFFERENCE(geom1, geom2)
ST_DIFFERENCE(geom1, geom2)
geom1 that does not intersect with geom2.ST_DIMENSION(geom)
ST_DIMENSION(geom)
geom, which is less than or equal to the coordinate
dimension. If geom is a single geometry, a 0 is for POINT, a 1 is for LINESTRING,
and a 2 is for POLYGON. If geom is a collection, it will return the largest dimension from
the collection. If geom is empty, 0 is returned.ST_DISJOINT(geom1, geom2)
ST_DISJOINT(geom1, geom2)
1 (true) if the given geometries, geom1 and geom2, do not spatially intersect.ST_DISTANCE(geom1, geom2[, solution])
ST_DISTANCE(geom1, geom2[, solution])
geom1 and geom2, using the
specified solution type. Solution types available:0(default) - Euclidean; returns 2-D Euclidean distance1- Haversine; returns minimum sphere distance in meters2- Vincenty; returns minimum spheroid distance in meters, more accurate than Haversine but slower performance
geom1 and geom2 intersect (verify using ST_INTERSECTS), the distance will
always be 0.ST_DISTANCEPOINTS (x1, y1, x2, y2[, solution])
ST_DISTANCEPOINTS (x1, y1, x2, y2[, solution])
x1, y1 and x2, y2, using the
specified solution type. Solution types available:0(default) - Euclidean; returns 2-D Euclidean distance1- Haversine; returns minimum sphere distance in meters2- Vincenty; returns minimum spheroid distance in meters, more accurate than Haversine but slower performance
ST_DFULLYWITHIN (geom1, geom2, distance[, solution])
ST_DFULLYWITHIN (geom1, geom2, distance[, solution])
1 (true) if the maximum distance between geometries geom1 and geom2 is less than
or equal to the specified distance of each other using the specified solution type. If geom1
or geom2 is null, 0 (false) is returned. Solution types available:0(default) - Euclidean; uses degrees to calculate distance1- Sphere; uses meters to calculate distance2- Spheroid; uses meters to calculate distance, more accurate than sphere but slower performance
ST_DWITHIN (geom1, geom2, distance[, solution])
ST_DWITHIN (geom1, geom2, distance[, solution])
1 (true) if the minimum distance between geometries geom1 and geom2 is within the
specified distance of each other using the specified solution type. Solution types available:0(default) - Euclidean; uses degrees to calculate distance1- Sphere; uses meters to calculate distance2- Spheroid; uses meters to calculate distance, more accurate than sphere but slower performance
ST_ELLIPSE(x, y, height, width)
ST_ELLIPSE(x, y, height, width)
x- the x coordinate or longitude used to center the ellipsey- the y coordinate or latitude used to center the ellipseheight- the height of the ellipse (in degrees)width- the width of the ellipse (in degrees)
ST_ENDPOINT(geom)
ST_ENDPOINT(geom)
geom as a POINT if it’s a LINESTRING. If geom is not
a LINESTRING, null is returned.ST_ENVDWITHIN (geom1, geom2, distance[, solution])
ST_ENVDWITHIN (geom1, geom2, distance[, solution])
1 (true) if geom1 is within the specified distance of the bounding box of
geom2 using the specified solution type. Solution types available:0(default) - Euclidean; uses degrees to calculate distance1- Sphere; uses meters to calculate distance
ST_ENVELOPE(geom)
ST_ENVELOPE(geom)
geom.ST_ENVINTERSECTS(geom1, geom2)
ST_ENVINTERSECTS(geom1, geom2)
1 (true) if the bounding box of the given geometries, geom1 and geom2, intersect.ST_EQUALS(geom1, geom2)
ST_EQUALS(geom1, geom2)
1 (true) if the given geometries, geom1 and geom2, are spatially equal. Note that
order does not matter.ST_EQUALSEXACT (geom1, geom2[, tolerance])
ST_EQUALSEXACT (geom1, geom2[, tolerance])
1 (true) if the given geometries, geom1 and geom2, are almost spatially equal
within some given tolerance. If the values within the given geometries are within the
tolerance value of each other, they’re considered equal, e.g., if tolerance is 2,
POINT(1 1) and POINT(1 3) are considered equal, but POINT(1 1) and POINT(1 3.1) are not. Note that
the geometry types have to match for them to be considered equal. The default tolerance is 0,
which makes this function effectively equivalent to ST_EQUALS(geom1, geom2) in the default case.ST_ERASE(geom1, geom2)
ST_ERASE(geom1, geom2)
geom1 equal to the size of geom2.ST_EXPAND(geom, units)
ST_EXPAND(geom, units)
units of the given geom. The
expansion can also be defined for separate directions by providing separate parameters for each
direction, e.g., ST_EXPAND(geom, unitsx, unitsy, unitsz, unitsm).ST_EXPANDBYRATE(geom, rate)
ST_EXPANDBYRATE(geom, rate)
rate (a ratio of width and height) for the given
geometry geom. The rate must be between 0 and 1.ST_EXTERIORRING(geom)
ST_EXTERIORRING(geom)
geomST_FORCE2D(geom)
ST_FORCE2D(geom)
geom, the provided geometry or
set of geometries (e.g., via GEOMETRYCOLLECTION or WKT column name).ST_FORCE3D(geom[, z])
ST_FORCE3D(geom[, z])
geom, a provided geometry or
set of geometries (e.g., via GEOMETRYCOLLECTION or WKT column name), using z as the geometry’s
new z-value. The provided z-values can also be derived from a numeric column. If no z is provided,
a 0 will be applied.geom and a numeric column is provided for z, the z
values will be matched to the provided geometries by row in the source table. If a singular
geometry is provided for geom and a column is provided for z, three-dimensional
versions of the provided geometry will be returned for each z value found in the provided
z column. If columns are provided for both geom and z and nulls are present in
either column, the row containing null values will be skipped in the results.ST_GENERATEPOINTS(geom, num)
ST_GENERATEPOINTS(geom, num)
num of randomly generated points within the boundary of
geom.ST_GEOHASH(geom[, precision])
ST_GEOHASH(geom[, precision])
geom with specified precision
(the length of the resulting geohash string). The longer the precision, the more precise the hash is. By
default, precision is set to 20; the max for precision is 32. Returns null if
geom is an empty geometry.See Geohash for an example.ST_GEOMETRYFROMTEXT(wkt)
ST_GEOMETRYFROMTEXT(wkt)
ST_GEOMFROMTEXT(wkt)ST_GEOMETRYN(geom, index)
ST_GEOMETRYN(geom, index)
index geometry back from the given geom geometry. The index starts from 1 and goes to
the number of geometries in geom.ST_GEOMETRYTYPE(geom)
ST_GEOMETRYTYPE(geom)
geom.ST_GEOMETRYTYPEID(geom)
ST_GEOMETRYTYPEID(geom)
geom. Type and ID mappings:- POINT = 0
- LINESTRING = 1
- POLYGON = 3
- MULTIPOINT = 4
- MULTILINESTRING = 5
- MULTIPOLYGON = 6
- GEOMETRYCOLLECTION = 7
ST_GEOMFROMGEOHASH (geohash[, precision])
ST_GEOMFROMGEOHASH (geohash[, precision])
geohash with a precision set by the integer
precision. If precision is specified, the function will use as many characters in the hash
equal to precision to create the geometry. If no precision is specified, the full length of
the geohash is used.See Geohash for an example.ST_GEOMFROMH3(h3_index)
ST_GEOMFROMH3(h3_index)
H3_CELLTOBOUNDARY; see H3 Functions.ST_GEOMFROMTEXT(wkt)
ST_GEOMFROMTEXT(wkt)
wkt. Note that this function is
only compatible with constants.ST_H3(wkt, resolution)
ST_H3(wkt, resolution)
H3_GEOMTOCELL; see H3 Functions.ST_HEXGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
ST_HEXGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
cell_side. The cell_side cannot be
greater than the width or height of the bounding box. The maximum number of cells that can be
produced is determined by limit, a positive integer. Supported values for limit:-1- No limit to the number of cells generated (effectively limited by system memory)0(default) - 100 million cells<n>- Custom limit ofncells
cell_side)
than the system limit, a null is returned.ST_INTERIORRINGN(geom, n)
ST_INTERIORRINGN(geom, n)
n-th interior LINESTRING ring of the POLYGON geom. If geom is not a POLYGON
or the given n is out of range, a null is returned. The index begins at 1ST_INTERSECTION(geom1, geom2)
ST_INTERSECTION(geom1, geom2)
geom1 and geom2ST_INTERSECTS(geom1, geom2)
ST_INTERSECTS(geom1, geom2)
1 (true) if the given geometries, geom1 and geom2, intersect in 2-DST_ISCLOSED(geom)
ST_ISCLOSED(geom)
1 (true) if the given geometry’s (geom) start and end points coincideST_ISCOLLECTION(geom)
ST_ISCOLLECTION(geom)
1 (true) if geom is a collection, e.g., GEOMETRYCOLLECTION, MULTIPOINT,
MULTILINESTRING, etc.ST_ISEMPTY(geom)
ST_ISEMPTY(geom)
1 (true) if geom is emptyST_ISRING(geom)
ST_ISRING(geom)
1 (true) if LINESTRING geom is both closed (per ST_ISCLOSED) and “simple”
(per ST_ISSIMPLE). Returns 0 if geom is not a LINESTRINGST_ISSIMPLE(geom)
ST_ISSIMPLE(geom)
1 (true) if geom has no anomalous geometric points, e.g., self-intersection or
self-tangencyST_ISVALID(geom)
ST_ISVALID(geom)
1 (true) if geom (typically a [MULTI]POLYGON) is well formed. A POLYGON is valid if
its rings do not cross, and its boundary intersects only at POINTs (not along a line). The POLYGON must
also not have dangling LINESTRINGs. A MULTIPOLYGON is valid if all of its elements are also valid, and
the interior rings of those elements do not intersect. Each element’s boundaries may touch but only
at POINTs (not along a line). ST_MAKEVALID(geom) can be used to help correct invalid geometries.ST_ISVALIDREASON(geom)
ST_ISVALIDREASON(geom)
Valid Geometry if geom is well formed, according to ST_ISVALID(geom); otherwise,
returns the reason geom is determined to be malformed. ST_MAKEVALID(geom) can be used to
help correct invalid geometries.Example:| Function Call | ST_ISVALIDREASON(‘POLYGON((-1 0, 1 0, 1 1, -1 -1))‘) |
| Return | Self-intersection[0 0] |
ST_LENGTH(geom[, solution])
ST_LENGTH(geom[, solution])
0 if
another type of geometry, e.g., POINT, MULTIPOINT, etc. GEOMETRYCOLLECTIONs are
also supported but the aforementioned type limitation still applies; the collection will be
recursively searched for LINESTRINGs and MULTILINESTRINGs and the summation of all supported geometry
types is returned (unsupported types are ignored). Solution types available:0(default) - 2D Euclidean length1- length on a sphere in meters2- length on a spheroid in meters
ST_LINEFROMMULTIPOINT(geom)
ST_LINEFROMMULTIPOINT(geom)
geom if it is a MULTIPOINT. Returns null if geom is not a
MULTIPOINTST_LINEINTERPOLATEPOINT(geom, frac)
ST_LINEINTERPOLATEPOINT(geom, frac)
geom that is the frac fraction of the distance along the line. If geom is either
empty or not a LINESTRING, null is returnedST_LINELOCATEPOINT(linestring, point)
ST_LINELOCATEPOINT(linestring, point)
linestring to the given point as a
value between 0 and 1. The return value is a fraction of the total linestring length.ST_LINEMERGE(geom)
ST_LINEMERGE(geom)
geom. If geom is a MULTILINESTRING
comprising LINESTRINGs with shared endpoints, a contiguous LINESTRING is returned. If geom is a
LINESTRING or a MULTILINESTRING comprising LINESTRINGS without shared endpoints, geom is returned
If geom is an empty (MULTI)LINESTRING or a (MULTI)POINT or (MULTI)POLYGON, an empty
GEOMETRYCOLLECTION is returned.ST_LINESUBSTRING (geom, start_frac, end_frac)
ST_LINESUBSTRING (geom, start_frac, end_frac)
geom LINESTRING from the point that is the start_frac fraction of the distance along
the line to the point that is the end_frac fraction of the distance along the line.For example, given LINESTRING(1 1, 2 2, 3 3) a start_fraction of 0 and an end_fraction of 0.25 would yield
the first quarter of the given LINESTRING, or LINESTRING(1 1, 1.5 1.5).Returns null in the following cases:- input geometry is (MULTI)POINT, MULTILINESTRING, or (MULTI)POLYGON
start_fracis greater thanend_fracstart_fracorend_fracare not between0&1, inclusive
ST_LONGESTLINE (geom1, geom2[, solution])
ST_LONGESTLINE (geom1, geom2[, solution])
geom1 or geom2 is
empty, null is returned. Solution types available:0(default) - Euclidean; uses degrees to calculate the longest line1- Sphere; uses meters to calculate the longest line2- Spheroid; uses meters to calculate the longest line, more accurate than sphere but slower performance
ST_MAKEENVELOPE (xmin, ymin, xmax, ymax)
ST_MAKEENVELOPE (xmin, ymin, xmax, ymax)
ST_MAKELINE(geom[, geom2])
ST_MAKELINE(geom[, geom2])
geom if it is a MULTIPOINT. If geom is a POINT, there must be at
least one other POINT to construct a LINESTRING. If geom is a LINESTRING, it must have at least
two points. Returns null if geom is not a POINT, MULTIPOINT, or LINESTRINGST_MAKEPOINT(x, y)
ST_MAKEPOINT(x, y)
ST_MAKEPOLYGON(geom)
ST_MAKEPOLYGON(geom)
geom. Inputs must be closed LINESTRINGsST_MAKETRIANGLE2D (x1, y1, x2, y2, x3, y3)
ST_MAKETRIANGLE2D (x1, y1, x2, y2, x3, y3)
ST_MAKETRIANGLE3D (x1, y1, z1, x2, y2, z2, x3, y3, z3)
ST_MAKETRIANGLE3D (x1, y1, z1, x2, y2, z2, x3, y3, z3)
ST_MAKEVALID(geom[, options])
ST_MAKEVALID(geom[, options])
geom into a valid geometry when it is malformed, as determined by
ST_ISVALID(geom). Returns geom if it is a valid geometry already. The method used to convert
invalid geometries into valid ones can be specified in options as a space-separated string of
x=y key/value pairs. The keys and corresponding values are as follows:-
method- the algorithm used to convert invalid geometries into valid ones; either:linework(default) - build geometry from lines extracted fromgeomstructure- build geometry from interior & exterior rings extracted fromgeom
-
keepcollapsed- if using themethodofstructure, whether to drop portions of the converted geometry that collapse to lower dimensions:true(default) - keep portions of geometry that collapse to lower dimensionsfalse- don’t keep portions of geometry that collapse to lower dimensions
| Function Call | ST_MAKEVALID(‘POLYGON((-1 0, 1 0, 1 1, -1 -1))‘) |
| Return | MULTIPOLYGON (((-1 -1, -1 0, 0 0, -1 -1)), ((1 0, 0 0, 1 1, 1 0))) |
| Function Call | ST_MAKEVALID(‘POLYGON((0 0, 0 0, 0 0, 0 0))’, ‘method=structure keepcollapsed=true’) |
| Return | POINT (0 0) |
| Function Call | ST_MAKEVALID(‘POLYGON((0 0, 0 0, 0 0, 0 0))’, ‘method=structure keepcollapsed=false’) |
| Return | POLYGON EMPTY |
ST_MAXDISTANCE (geom1, geom2[, solution])
ST_MAXDISTANCE (geom1, geom2[, solution])
geom1 and geom2 geometries using the specified
solution type. If geom1 or geom2 is empty, null is returned. Solution types available:0(default) - returns maximum 2-D Euclidean distance1- Sphere; returns maximum distance in meters2- Spheroid; returns maximum distance in meters, more accurate than sphere but slower performance
ST_MAXX(geom)
ST_MAXX(geom)
geom geometry. This function
works for 2-D and 3-D geometries.ST_MAXY(geom)
ST_MAXY(geom)
geom geometry. This function
works for 2-D and 3-D geometries.ST_MAXZ(geom)
ST_MAXZ(geom)
geom geometry. This function
works for 2-D and 3-D geometries.ST_MINX(geom)
ST_MINX(geom)
geom geometry. This function
works for 2-D and 3-D geometries.ST_MINY(geom)
ST_MINY(geom)
geom geometry. This function
works for 2-D and 3-D geometries.ST_MINZ(geom)
ST_MINZ(geom)
geom geometry. This function
works for 2-D and 3-D geometries.ST_MULTI(geom)
ST_MULTI(geom)
geom as a MULTI- geometry, e.g., a POINT would return a MULTIPOINT.ST_MULTIPLERINGBUFFERS (geom, distance[, outside])
ST_MULTIPLERINGBUFFERS (geom, distance[, outside])
distance around the given geom geometry. Multiple
distances are specified as comma-separated values in an array, e.g., [10,20,30]. Valid values for
outside are:FULL- indicates that buffers will overlap or cover the givengeomgeometry. This is the default.OUTSIDE_ONLY- indicates that buffers will be rings around the givengeomgeometry.
ST_NDIMS(geom)
ST_NDIMS(geom)
geom. For X,Y data, this will return 2; if a Z component is
present, it will return 3.ST_NEAR(geom1, geom2)
ST_NEAR(geom1, geom2)
geom2 that is closest to geom1. If geom2 is a singular geometry
object (e.g., POINT, LINESTRING, POLYGON), geom2 will be returned. If geom2 a multi-geometry,
e.g., MULTIPOINT, MULTILINESTRING, etc., the nearest singular geometry in geom2 will be
returned.ST_NORMALIZE(geom)
ST_NORMALIZE(geom)
geom in its normalized (canonical) form, which may rearrange the points in lexicographical
order.ST_NPOINTS(geom)
ST_NPOINTS(geom)
geom.ST_NRINGS(geom)
ST_NRINGS(geom)
geom. For non-polygonal geometries,
it will return 0. For MULTIPOLYGONs, it will return the total number of rings across all components.ST_NUMGEOMETRIES(geom)
ST_NUMGEOMETRIES(geom)
geom is a collection or MULTI- geometry, returns the number of geometries. If geom is a
single geometry, returns 1.ST_NUMINTERIORRINGS(geom)
ST_NUMINTERIORRINGS(geom)
geom is a POLYGON. Returns null if geom is
anything else.ST_NUMPOINTS(geom)
ST_NUMPOINTS(geom)
geom LINESTRING. Returns null if geom is not a
LINESTRING.ST_OVERLAPS(geom1, geom2)
ST_OVERLAPS(geom1, geom2)
1 (true) if given geometries geom1 and geom2 share space. If geom1 and/or
geom2 are a GEOMETRYCOLLECTION, a 0 is returned regardless of if the two geometries overlapST_PARTITION(geom[, threshold])
ST_PARTITION(geom[, threshold])
geom partitioned into a number of POLYGONs with a
maximum number of vertices equal to the given threshold. Minimum value for threshold is
10; default value is 10000. If geom is not a POLYGON or MULTIPOLYGON, geom is
returned. If the number of vertices in geom is less than the threshold, geom is returned.ST_PERIMETER(geom[, solution])
ST_PERIMETER(geom[, solution])
0 if another
type of geometry, e.g., POINT, MULTIPOINT, LINESTRING, or MULTILINESTRING. GEOMETRYCOLLECTIONs are
also supported but the aforementioned type limitation still applies; the collection will be
recursively searched for POLYGONs and MULTIPOLYGONs and the summation of all supported geometry types
is returned (unsupported types are ignored). Solution types available:0(default) - 2D Euclidean length1- length on a sphere in meters2- length on a spheroid in meters
ST_POINT(x, y)
ST_POINT(x, y)
x and y coordinates.ST_POINTFROMGEOHASH (geohash[, precision])
ST_POINTFROMGEOHASH (geohash[, precision])
geohash with a precision set by the integer precision. If
precision is specified, the function will use as many characters in the hash equal to
precision to create the geometry. If no precision is specified, the full length of
the geohash is used.ST_POINTGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
ST_POINTGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
cell_side. The cell_side cannot be
greater than the width or height of the bounding box. The maximum number of cells that can be
produced is determined by limit, a positive integer. Supported values for limit:-1- No limit to the number of cells generated (effectively limited by system memory)0(default) - 100 million cells<n>- Custom limit ofncells
cell_side)
than the system limit, a null is returned.ST_POINTN(geom, n)
ST_POINTN(geom, n)
n-th point in LINESTRING geom. Negative values are valid, but note that they are
counted backwards from the end of geom. A null is returned if geom is not a LINESTRING.ST_POINTS(geom)
ST_POINTS(geom)
geom.ST_PROJECT(geom, distance, azimuth)
ST_PROJECT(geom, distance, azimuth)
geom along a geodesic calculated using distance
and azimuth. If geom is not a POINT, null is returned.ST_REMOVEPOINT(geom, offset)
ST_REMOVEPOINT(geom, offset)
geom using offset to skip over POINTs in the LINESTRING. The
offset is 0-based.ST_REMOVEREPEATEDPOINTS (geom, tolerance)
ST_REMOVEREPEATEDPOINTS (geom, tolerance)
geom if the point’s vertices are greater than or equal to the tolerance
of the previous point in the geometry’s list. If geom is not a MULTIPOINT, MULTILINESTRING, or a
MULTIPOLYGON, no points will be removed.ST_REVERSE(geom)
ST_REVERSE(geom)
ST_ROTATE(geom, radians[, wkt])
ST_ROTATE(geom, radians[, wkt])
geom counter-clockwise by radians radians. Optionally, the rotation origin can be provided as a WKT POINT
WKT POINT (wkt). If not provided, geom will be rotated around (0, 0).ST_ROTATE(geom, radians[, x, y])
ST_ROTATE(geom, radians[, x, y])
geom counter-clockwise by radians radians. Optionally, the rotation origin can be provided as a coordinate
pair (x & y). If not provided, geom will be rotated around (0, 0).ST_SCALE(geom, wkt)
ST_SCALE(geom, wkt)
geom by multiplying its respective vertices by the corresponding x, y values in the given WKT POINT.| Function Call | ST_SCALE(‘POLYGON((1 2, -2 1, -1 -2, 2 -1, 1 2))’, GEOMETRY(‘POINT(3 5)‘)) |
| Return | POLYGON ((3 10, -6 5, -3 -10, 6 -5, 3 10)) |
ST_SCALE(geom, x, y)
ST_SCALE(geom, x, y)
geom by multiplying its respective vertices by the given x & y values.| Function Call | ST_SCALE(‘POLYGON((1 2, -2 1, -1 -2, 2 -1, 1 2))’, 3, 5) |
| Return | POLYGON ((3 10, -6 5, -3 -10, 6 -5, 3 10)) |
ST_SEGMENTIZE (geom, max_segment_size[, solution])
ST_SEGMENTIZE (geom, max_segment_size[, solution])
geom, but segmentized n number of times depending on how the
max_segment_size distance (in units based on the solution type) divides up the original
geometry. The new geom is guaranteed to have segments that are smaller than the given
max_segment_size. Note that POINTs are not able to be segmentized. Collection geometries
(GEOMETRYCOLLECTION, MULTILINESTRING, MULTIPOINT, etc.) can be segmentized, but only the individual
parts will be segmentized, not the collection as a whole. Solution types available:0- Euclidean; uses degrees to calculate distance1(default) - Sphere; uses meters to calculate distance
ST_SETPOINT(geom1, position, geom2)
ST_SETPOINT(geom1, position, geom2)
geom1 with POINT geom2 at position (base 0). Negative
values are valid, but note that they are counted backwards from the end of geom.ST_SHAREDPATH(geom1, geom2)
ST_SHAREDPATH(geom1, geom2)
ST_SHORTESTLINE(geom1, geom2)
ST_SHORTESTLINE(geom1, geom2)
geom1 or geom2
is empty, null is returnedST_SIMPLIFY(geom, tolerance)
ST_SIMPLIFY(geom, tolerance)
geom using an algorithm to reduce the number of points
comprising a given geometry while attempting to best retain the original shape. The given
tolerance determines how much to simplify the geometry. The higher the tolerance, the more
simplified the returned geometry. Some holes might be removed and some invalid polygons (e.g.,
self-intersecting, etc.) might be present in the returned geometry. Only (MULTI)LINESTRINGs and
(MULTI)POLYGONs can be simplified, including those found within GEOMETRYCOLLECTIONs; any other
geometry objects will be returned unsimplified.tolerance should be provided in the same units as the data. As a rule of thumb,
a tolerance of 0.00001 would correspond to about one meter.ST_SIMPLIFYPRESERVETOPOLOGY (geom, tolerance)
ST_SIMPLIFYPRESERVETOPOLOGY (geom, tolerance)
geom using an algorithm to reduce the number of points
comprising a given geometry while attempting to best retain the original shape. The given
tolerance determines how much to simplify the geometry. The higher the tolerance, the more
simplified the returned geometry. No holes will be removed and no invalid polygons (e.g.,
self-intersecting, etc.) will be present in the returned geometry. Only (MULTI)LINESTRINGs and
(MULTI)POLYGONs can be simplified, including those found within GEOMETRYCOLLECTIONs; any other
geometry objects will be returned unsimplified.tolerance should be provided in the same units as the data. As a rule of thumb,
a tolerance of 0.00001 would correspond to about one meter.ST_SNAP(geom1, geom2, tolerance)
ST_SNAP(geom1, geom2, tolerance)
geom1 to geom2 within the given tolerance. If the tolerance causes geom1
to not snap, the geometries will be returned unchanged.ST_SPLIT(geom1, geom2)
ST_SPLIT(geom1, geom2)
geom1 and geom2
geometries.ST_SQUAREGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
ST_SQUAREGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
cell_side. The cell_side cannot be
greater than the width or height of the bounding box. The maximum number of cells that can be
produced is determined by limit, a positive integer. Supported values for limit:-1- No limit to the number of cells generated (effectively limited by system memory)0(default) - 100 million cells<n>- Custom limit ofncells
cell_side)
than the system limit, a null is returned.ST_STARTPOINT(geom)
ST_STARTPOINT(geom)
geom as a POINT. Returns null if geom is not a
LINESTRING.ST_SYMDIFFERENCE(geom1, geom2)
ST_SYMDIFFERENCE(geom1, geom2)
geom1 and geom2 geometries that do not
intersect.ST_TOUCHES(geom1, geom2)
ST_TOUCHES(geom1, geom2)
1 (true) if the given geometries, geom1 and geom2, have at least one point in
common but their interiors do not intersect. If geom1 and/or geom2 are a GEOMETRYCOLLECTION,
a 0 is returned regardless of if the two geometries touchST_TRANSLATE (geom, deltax, deltay[, deltaz])
ST_TRANSLATE (geom, deltax, deltay[, deltaz])
geom by given offsets deltax and deltay. A z-coordinate offset can be applied
using deltaz.
intersect.ST_TRIANGLEGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
ST_TRIANGLEGRID (xmin, ymin, xmax, ymax, cell_side[, limit])
cell_side. The cell_side cannot be
greater than the width or height of the bounding box. The maximum number of cells that can be
produced is determined by limit, a positive integer. Supported values for limit:-1- No limit to the number of cells generated (effectively limited by system memory)0(default) - 100 million cells<n>- Custom limit ofncells
cell_side)
than the system limit, a null is returned.ST_UNION(geom1, geom2)
ST_UNION(geom1, geom2)
geom1 and
geom2.ST_UNIONCOLLECTION(geom)
ST_UNIONCOLLECTION(geom)
geom.ST_UPDATE(geom1, geom2)
ST_UPDATE(geom1, geom2)
geom1 geometry updated by geom2 geometryST_VORONOIPOLYGONS(geom[, tolerance])
ST_VORONOIPOLYGONS(geom[, tolerance])
geom than any other vertices in geom) calculated from the vertices in geom
and the given tolerance. The tolerance determines the distance at which points will be
considered the same. An empty GEOMETRYCOLLECTION is returned if geom is an empty geometry, a
single POINT, or a LINESTRING or POLYGON composed of equivalent vertices (e.g.,
POLYGON((0 0, 0 0, 0 0, 0 0)), LINESTRING(0 0, 0 0)).If no tolerance is specified, no vertices will be considered the same; each will have its own polygon.The bounding box for the result POLYGONs extends past the four edges of the input geom bounding box by
an amount that is the greater of the input bounding box’s height and width. For instance, an input geom
with a 3 x 4 bounding box will result in Voronoi polygons filling a space that is 11 x 12.ST_WITHIN(geom1, geom2)
ST_WITHIN(geom1, geom2)
1 (true) if the geom1 geometry is inside the geom2 geometry. Note that as long as
at least one point is inside of geom2, geom1 is considered within geom2 even if the rest
of the geom1 lies along the boundary of geom2ST_WKBTOWKT(geom)
ST_WKBTOWKT(geom)
ST_WKTTOWKB(geom)
ST_WKTTOWKB(geom)
ST_X(geom)
ST_X(geom)
geom; if the coordinate is not available, null is
returned. geom must be a POINT.ST_XMAX(geom)
ST_XMAX(geom)
ST_MAXX()ST_XMIN(geom)
ST_XMIN(geom)
ST_MINX()ST_Y(geom)
ST_Y(geom)
geom; if the coordinate is not available, null is
returned. geom must be a POINT.ST_YMAX(geom)
ST_YMAX(geom)
ST_MAXY()ST_YMIN(geom)
ST_YMIN(geom)
ST_MINY()ST_ZMAX(geom)
ST_ZMAX(geom)
ST_MAXZ()ST_ZMIN(geom)
ST_ZMIN(geom)
ST_MINZ()Aggregation Functions
The following functions can be used on geospatial/geometry columns within aggregations.ST_AGGREGATE_COLLECT(geom)
ST_AGGREGATE_COLLECT(geom)
ST_COLLECT_AGGREGATE()ST_AGGREGATE_INTERSECTION(geom)
ST_AGGREGATE_INTERSECTION(geom)
ST_INTERSECTION_AGGREGATE()ST_COLLECT_AGGREGATE(geom)
ST_COLLECT_AGGREGATE(geom)
geom set.
Any MULTI* geometries will be divided into separate singular geometries, e.g.,
MULTIPOINT((0 0), (1 1)) would be divided into POINT(0 0) and POINT(1 1) in the
results; the same is true for elements of a GEOMETRYCOLLECTION found in geom,
where a GEOMETRYCOLLECTION within the provided geom set will also be parsed,
effectively flattening it and adding the individual geometries to the resulting
GEOMETRYCOLLECTION. Any empty geometries in geom are ignored even if they are
part of a GEOMETRYCOLLECTION. Any duplicate WKTs will be retained.ST_DISSOLVE(geom)
ST_DISSOLVE(geom)
ST_DISSOLVEOVERLAPPING(geom)
ST_DISSOLVEOVERLAPPING(geom)
ST_INTERSECTION_AGGREGATE(geom)
ST_INTERSECTION_AGGREGATE(geom)
geom set. Returns an empty GEOMETRYCOLLECTION if
there is no shared portion between all geometries. Functionally equivalent to
ST_INTERSECTION(ST_INTERSECTION(geom1, geom2), ... geomN).ST_LINESTRINGFROMORDEREDPOINTS(x, y, t)
ST_LINESTRINGFROMORDEREDPOINTS(x, y, t)
x, y)
ordered by the given sort column t (e.g., a timestamp or sequence number). If
any of the values in the specified columns are null, the null “point” will be
left out of the resulting LINESTRING. If there’s only one non-null “point” in the
source table, a POINT is returned. If there are no non-null “points” in the
source table, a null is returned.ST_LINESTRINGFROMORDEREDPOINTS3D(x, y, z, t)
ST_LINESTRINGFROMORDEREDPOINTS3D(x, y, z, t)
x, y, z) ordered by the given sort column t (e.g., a timestamp
or sequence number). If any of the values in the specified columns are null,
the null “point” will be left out of the resulting LINESTRING. If there’s only
one non-null “point” in the source table, a POINT is returned. If there are no
non-null “points” in the source table, a null is returned.ST_POLYGONIZE(geom)
ST_POLYGONIZE(geom)
Track Functions
The following functions are available in both SQL and the native API.ST_TRACKDURATION([unit,] t)
ST_TRACKDURATION([unit,] t)
unit, spanned by timestamp values in column
t. Grouping by track ID will return the duration per track.The duration can be returned in any of the following date/time units:YEARMONTHDAYHOURMINUTESECONDMILLISECOND
unit is MILLISECOND.ST_TRACKLENGTH(lat, lon, t[, solution])
ST_TRACKLENGTH(lat, lon, t[, solution])
lat &
lon and whose ordering is determined by an ascending sort on the timestamp t.
Length can be returned with any of the following solution types:| Type | Description |
|---|---|
0 | 2D Euclidean length in degrees |
1 | (default) Length on a sphere in meters |
2 | Length on a spheroid in meters |
ST_TRACK_DWITHIN
TheST_TRACK_DWITHIN table function finds tracks that are related, within
spatial or temporal bounds (or both) to the given track(s). The track(s) to use
as the filter criteria will be specified by the SEARCH_* parameters. The
TRACK_* parameters specify the set of tracks to search through for a match.
ST_TRACK_DWITHIN function follows.
TRACK_TABLE
TRACK_TABLE
SEARCH_* data set.To perform a search on the flights table, pass the name of the table to INPUT_TABLE:INPUT_TABLE:TRACK_ID_COLUMN
TRACK_ID_COLUMN
TRACK_X_COLUMN
TRACK_X_COLUMN
TRACK_Y_COLUMN
TRACK_Y_COLUMN
TRACK_ORDER_COLUMN
TRACK_ORDER_COLUMN
SEARCH_TABLE
SEARCH_TABLE
TRACK_* data set.To match tracks from the flights_of_interest table, pass the name of the table to INPUT_TABLE:INPUT_TABLE:SEARCH_ID_COLUMN
SEARCH_ID_COLUMN
SEARCH_X_COLUMN
SEARCH_X_COLUMN
SEARCH_Y_COLUMN
SEARCH_Y_COLUMN
SEARCH_ORDER_COLUMN
SEARCH_ORDER_COLUMN
SEARCH_XY_DISTANCE
SEARCH_XY_DISTANCE
SPATIAL_SOLUTION_TYPE of 0.| Unit | Description |
|---|---|
f | Feet |
ki | Kilometers |
m | (default) Meters |
mi | Miles |
SPATIAL_SOLUTION_TYPE
SPATIAL_SOLUTION_TYPE
| Type | Description |
|---|---|
0 | (default) 2D Euclidean length in degrees |
1 | Length on a sphere, returned in units specified by SEARCH_XY_DISTANCE |
2 | Length on a spheroid, returned in units specified by SEARCH_XY_DISTANCE |
SEARCH_TIME_DISTANCE
SEARCH_TIME_DISTANCE
| Unit | Description |
|---|---|
ms | Milliseconds |
s | (default) Seconds |
m | Minutes |
h | Hours |
d | Days |
w | Weeks |
months | Months |
y | Years |
ST_TRACKINTERSECTS
TheST_TRACKINTERSECTS table function finds tracks pass through the given
geofence(s). The geofence(s) use as the filter will be specified by the
GEOFENCE_* parameters. The TRACK_* parameters specify the set of
tracks to search through for any intersecting the geofence(s).
The result will include a record for each intersecting track & geofence pair,
with:
- a
LINESTRINGrepresenting the full track intersecting a geofence - a
LINESTRINGrepresenting the geofence it intersected
ST_TRACKINTERSECTS function follows.
TRACK_TABLE
TRACK_TABLE
SEARCH_* data
set.To perform a search on the flights table, pass the name of the table to INPUT_TABLE:INPUT_TABLE:TRACK_ID_COLUMN
TRACK_ID_COLUMN
TRACK_X_COLUMN
TRACK_X_COLUMN
TRACK_Y_COLUMN
TRACK_Y_COLUMN
TRACK_ORDER_COLUMN
TRACK_ORDER_COLUMN
GEOFENCE_TABLE
GEOFENCE_TABLE
TRACK_* data set.To search for tracks intersecting the geofence(s) from the flight_area_of_interest table, pass the
name of the geofence table to INPUT_TABLE:INPUT_TABLE:GEOFENCE_ID_COLUMN
GEOFENCE_ID_COLUMN
GEOFENCE_WKT_COLUMN
GEOFENCE_WKT_COLUMN
H3 Functions
The functions below support various operations using the H3 geospatial indexing scheme.H3_CELLTOBOUNDARY(h3_index)
H3_CELLTOBOUNDARY(h3_index)
h3_index.See Geohash-H3 for an example.H3_CELLTOCENTERCHILD(h3_index, res)
H3_CELLTOCENTERCHILD(h3_index, res)
H3_CELLTOFIRSTCHILD.H3_CELLTOCHILDN(h3_index, res, i)
H3_CELLTOCHILDN(h3_index, res, i)
i th child at resolution res for the given
h3_index. The value i should be less than the number of children returned from calling
H3_CELLTOCHILDRENSIZE(h3_index, res).H3_CELLTOCHILDPOS(h3_index, res)
H3_CELLTOCHILDPOS(h3_index, res)
h3_index within an ordered list of the children of the cell’s
parent at resolution res. This is the inverse of H3_CHILDPOSTOCELL (H3_CELLTOCHILDN).H3_CELLTOCHILDRENSIZE(h3_index, res)
H3_CELLTOCHILDRENSIZE(h3_index, res)
res for the given h3_index.H3_CELLTOFIRSTCHILD(h3_index, res)
H3_CELLTOFIRSTCHILD(h3_index, res)
res for the given h3_index.This is equivalent to H3_CELLTOCHILDN(h3_index,res,0).H3_CELLTOLASTCHILD(h3_index, res)
H3_CELLTOLASTCHILD(h3_index, res)
res for the given h3_index.This is equivalent to H3_CELLTOCHILDN(h3_index,res,H3_CELLTOCHILDRENSIZE(h3_index, res)-1).H3_CELLTOPARENT(h3_index, res)
H3_CELLTOPARENT(h3_index, res)
h3_index at resolution res.H3_CELLTOXY(h3_index)
H3_CELLTOXY(h3_index)
h3_index.H3_CHILDPOSTOCELL(i, h3_index, res)
H3_CHILDPOSTOCELL(i, h3_index, res)
H3_CELLTOCHILDN(h3_index, res, i).H3_GEOMTOCELL(geom, res)
H3_GEOMTOCELL(geom, res)
geom with the given resolution res. The higher the resolution, the more precise the index
is. The resolution res must be an integer between 0 and 15.See Geohash-H3 for an example.H3_GETRESOLUTION(h3_index)
H3_GETRESOLUTION(h3_index)
h3_index.H3_GRIDDISK(h3_index, k)
H3_GRIDDISK(h3_index, k)
k from the provided H3 index h3_index.H3_GRIDDISKN(h3_index, k, i)
H3_GRIDDISKN(h3_index, k, i)
i th H3 index within a given distance k from the provided H3 index
h3_index. This function would typically be used in conjunction with H3_NUMGRIDDISK via iter-join.
The value of i should be between 0 and the result of H3_NUMGRIDDISK(h3_index, k) - 1.H3_GRIDRING(h3_index, k)
H3_GRIDRING(h3_index, k)
k from the provided
H3 index h3_index.H3_H3TOSTRING(h3_index)
H3_H3TOSTRING(h3_index)
h3_index.H3_STRINGTOH3.H3_ISVALID(h3_index)
H3_ISVALID(h3_index)
1 (true) if the given H3 index h3_index is a valid H3 index value; otherwise
returns 0 (false).H3_LATLNGTOCELL (latitude, longitude, res)
H3_LATLNGTOCELL (latitude, longitude, res)
latitude and longitude
coordinate, with the given resolution res. The higher the resolution, the more precise the index
is. The resolution res must be an integer between 0 and 15.Equivalent to H3_XYTOCELL(longitude, latitude, res).H3_NUMGRIDDISK(h3_index, k)
H3_NUMGRIDDISK(h3_index, k)
k from the provided H3 index h3_index. This function
would typically be used in conjunction with H3_GRIDDISKN via iter-join.H3_NUMPOLYGONTOCELLS(geom, res)
H3_NUMPOLYGONTOCELLS(geom, res)
res that are within the given geometry geom.
Only polygon geometries are supported. This function would typically be used in conjunction with
H3_POLYGONTOCELLSN via iter-join.H3_POLYGONTOCELLS(geom, res)
H3_POLYGONTOCELLS(geom, res)
res that are within the given geometry geom.
Only polygon geometries are supported.H3_POLYGONTOCELLSN(geom, res, i)
H3_POLYGONTOCELLSN(geom, res, i)
i th H3 index at the given resolution res that is within the given geometry
geom. Only polygon geometries are supported. This function would typically be used in conjunction with
H3_NUMPOLYGONTOCELLS via iter-join. The value of i should be between 0 and the value returned
from H3_NUMPOLYGONTOCELLS(geom, res) - 1.H3_STRINGTOH3(h3_string)
H3_STRINGTOH3(h3_string)
h3_string.H3_H3TOSTRING.H3_XYTOCELL(x, y, res)
H3_XYTOCELL(x, y, res)
x and y coordinate,
with the given resolution res. The higher the resolution, the more precise the index is. The
resolution res must be an integer between 0 and 15.Equivalent to H3_LATLNGTOCELL(y, x, res).See Geohash-H3 for an example.JSON Functions
Scalar Functions
These functions can be applied to individual json column values, as well as array & string columns. However, for some functions to work as expected, the array or string value may need to be cast to JSON first.JSON(expr)
JSON(expr)
expr to JSON data typeExamples:| Function Call | Result |
|---|---|
JSON(‘[1, 2, “C”]’) | [1,2,“C”] |
JSON(’{“A”: “B”, “C”: {“D”: 5, “F”: 7}}’) | {“A”:“B”,“C”:{“D”:5,“F”:7}} |
JSON(null) | null |
JSON_ARRAY (value[,...] <null_hand>)
JSON_ARRAY (value[,...] <null_hand>)
<null_hand> parameter can be added to the end of the list to specify
handling of null values, though, at present, this only exists for compatibility with
other databases’ syntax—the option will be ignored and all null values will be added
to the array as null. Accepted null handling options:NULL ON NULL
| Function Call | Result |
|---|---|
JSON_ARRAY(1, 2, ‘C’) | [1,2,“C”] |
JSON_ARRAY(JSON(’{“A”: “B”}’), JSON(’{“C”: 4}’)) | [{“A”:“B”},{“C”:4}] |
JSON_ARRAY(1, null, ‘C’ NULL ON NULL) | [1,null,“C”] |
JSON_ARRAY_APPEND(arr, value)
JSON_ARRAY_APPEND(arr, value)
value to the given array arr of type string, array, or JSONExamples:| Function Call | Result |
|---|---|
JSON_ARRAY_APPEND(‘[1, 2]’, ‘C’) | [1,2,“C”] |
JSON_ARRAY_APPEND(’{“A”: “B”}’, JSON(’{“C”: 4}’)) | [{“A”:“B”},{“C”:4}] |
JSON_ARRAY_CONTAINS (json, path, val)
JSON_ARRAY_CONTAINS (json, path, val)
json contains the primitive value val at the JSON
query path, pathExamples:| Function Call | Result |
|---|---|
JSON_ARRAY_CONTAINS(‘[1, 2]’, ’$’, 2) | true |
JSON_ARRAY_CONTAINS(‘[1, 2]’, ’$’, ‘C’) | false |
JSON_ARRAY_CONTAINS(’{“A”: [2, 3]}’, ’$.A’, 2) | true |
JSON_ARRAY_CONTAINS(’{“A”: {“B”: [3, 4]}}’, ’$[“A”][“B”]’, 4) | true |
JSON_CARDINALITY(json)
JSON_CARDINALITY(json)
JSON_LENGTHJSON_EXISTS(json, path)
JSON_EXISTS(json, path)
json contains the JSON query path, pathExamples:| Function Call | Result |
|---|---|
JSON_EXISTS(‘[1, 2]’, ’$‘) | true |
JSON_EXISTS(‘[1, 2]’, ’$.A’) | false |
JSON_EXISTS(’{“A”: [2, 3]}’, ’$.A’) | true |
JSON_EXISTS(’{“A”: {“B”: 3, “D”: 5}}’, ’$[“A”][“D”]‘) | true |
JSON_KEYS(json, path)
JSON_KEYS(json, path)
path in json; null, if the
path doesn’t exist or contains a non-object (non-map) valueExamples:| Function Call | Result |
|---|---|
JSON_KEYS(’{}’, ’$’) | [] |
JSON_KEYS(‘[1, 2]’, ’$.A’) | null |
JSON_KEYS(’{“A”: [2, 3]}’, ’$’) | [“A”] |
JSON_KEYS(’{“A”: {“B”: 3, “D”: 5}}’, ’$[“A”]’) | [“B”,“D”] |
JSON_KEYS(’{“A”: {“B”: 3, “D”: 5}}’, ’$[“A”][“D”]‘) | null |
JSON_KEYS(’{“A”: {“B”: 3, “D”: {}}}’, ’$[“A”][“D”]’) | [] |
JSON_LENGTH(json[, path])
JSON_LENGTH(json[, path])
json, or at the
level of the optional JSON pathExamples:| Function Call | Result |
|---|---|
JSON_LENGTH(’{}‘) | 0 |
JSON_LENGTH(’[]‘) | 0 |
JSON_LENGTH(‘[1, 2]‘) | 2 |
JSON_LENGTH(’{“A”: [2, 3]}‘) | 1 |
JSON_LENGTH(’{“A”: {“B”: 3}, “D”: “E”}‘) | 2 |
JSON_LENGTH(’{“A”: [2, 3]}’, ’$.A’) | 2 |
JSON_LENGTH(’{“A”: {“B”: 3}, “D”: “E”}’, ’$.A’) | 1 |
JSON_MAKE_ARRAY(value)
JSON_MAKE_ARRAY(value)
valueExamples:| Function Call | Result |
|---|---|
JSON_MAKE_ARRAY(1) | [1] |
JSON_MAKE_ARRAY(JSON_ARRAY(1,2,3)) | [[1,2,3]] |
JSON_MAKE_ARRAY(JSON(’{“A”: “B”}’)) | [{“A”:“B”}] |
JSON_OBJECT (value[,...] <null_hand>)
JSON_OBJECT (value[,...] <null_hand>)
value setAn optional <null_hand> parameter can be added to the end of the list to specify
handling of null values, though, at present, this only exists for compatibility with
other databases’ syntax—the option will be ignored and all null values will be added
to the array as null. Accepted null handling options:NULL ON NULL
| Function Call | Result |
|---|---|
JSON_OBJECT() | {} |
JSON_OBJECT(‘A’: 2) | {“A”:2} |
JSON_OBJECT(‘A’ VALUE 2) | {“A”:2} |
JSON_OBJECT(KEY ‘A’ VALUE 2) | {“A”:2} |
JSON_OBJECT(‘A’: ‘B’, ‘C’: null NULL ON NULL) | {“A”:“B”,“C”:null} |
JSON_PRETTY(json)
JSON_PRETTY(json)
json objectExamples:| Function Call | JSON_PRETTY(‘[1,2,“C”]‘) |
| Return | |
| Function Call | JSON_PRETTY(’{“A”: “B”, “C”: {“D”: 5, “F”: 7}}‘) |
| Return | |
JSON_QUERY (json, path [<return>])
JSON_QUERY (json, path [<return>])
path in json; null, if the path doesn’t exist
or contains a primitive (non-object) valueAn optional return clause can be added to the end of the path to specify the return type
of the object found, as well as the error handling for the object lookup. The format of the
clause is:| Parameter | Description |
|---|---|
<wrapper> | Whether the returned object(s) should be wrapped in an array before being returned Valid wrapping schemes include:
|
<empty hand> | The scheme to use for handling empty returned objects Valid schemes include:
|
<error hand> | The scheme to use for handling errors in looking up the object Valid schemes include:
|
| Function Call | Result |
|---|---|
JSON_QUERY(‘[1, 2]’, ’$’) | [1,2] |
JSON_QUERY(‘[1, 2]’, ’$.A’) | null |
JSON_QUERY(’{“A”: [2, 3]}’, ’$.A’) | [2,3] |
JSON_QUERY(’{“A”: {“B”: 3, “D”: 5}}’, ’$[“A”]’) | {“B”:3,“D”:5} |
JSON_QUERY(’{“A”: {“B”: 3, “D”: 5}}’, ’$[“A”][“D”]‘) | null |
JSON_QUERY(’{“A”: {“B”: 3, “D”: [5, 6]}}’, ’$[“A”][“D”]’) | [5,6] |
JSON_QUERY(’{“A”: []}’, ’$.B’ EMPTY ARRAY ON EMPTY) | [] |
JSON_QUERY(’{“A”: 0}’, ’$.A’ EMPTY OBJECT ON ERROR) | {} |
JSON_QUERY(’{“A”: 2, “C”: 4}’, ’$.*‘) | null |
JSON_QUERY(’{“A”: 2, “C”: 4}’, ’$.*’ WITH WRAPPER) | [2,4] |
JSON_REPLACE(json, path, repl)
JSON_REPLACE(json, path, repl)
json with the value at the JSON path path replaced with the
replacement value replExamples:| Function Call | Result |
|---|---|
JSON_REPLACE(‘[1, 2]’, ’$’, ‘[3, 4]’) | [3,4] |
JSON_REPLACE(‘[1, 2]’, ’$.A’, ‘“B”’) | [1,2] |
JSON_REPLACE(’{“A”: [2, 3]}’, ’$.A’, ’{“D”: 5}’) | {“A”:{“D”:5}} |
JSON_REPLACE(’{“A”: {“B”: 3}}’, ’$[“A”]’, ‘“D”’) | {“A”:“D”} |
JSON_REPLACE(’{“A”: {“B”: [3, 4]}}’, ’$[“A”][“B”]’, 5) | {“A”:{“B”:5}} |
JSON_TYPE(expr)
JSON_TYPE(expr)
expr| Expression Type | JSON Type |
|---|---|
BOOLEAN | BOOLEAN |
| LONG |
| DOUBLE |
|
|
ARRAY (any) | ARRAY |
JSON_VALUE (json, path [return])
JSON_VALUE (json, path [return])
path in json; null, if the path doesn’t exist
or contains an object (non-primitive) valueAn optional return clause can be added to the end of the path to specify the return type
of the value found, as well as the error handling for the value lookup. The format of the
clause is:| Parameter | Description |
|---|---|
<type> | The JSON type of the value to return; if the value is not already of that type, it will be cast to that type, if possible Valid types include:
|
<empty hand> | The scheme to use for handling empty returned values Valid schemes include:
|
<error hand> | The scheme to use for handling errors in looking up the value Valid schemes include:
|
| Function Call | Result |
|---|---|
JSON_VALUE(‘1’, ’$‘) | 1 |
JSON_VALUE(‘[1, 2]’, ’$.A’) | null |
JSON_VALUE(’[“A”, “B”]’, ‘$.1’) | B |
JSON_VALUE(’{“A”: [2, 3]}’, ’$[“A”][“1”]‘) | 3 |
JSON_VALUE(’{“A”: {“B”: 3, “D”: 5}}’, ’$[“A”][“D”]‘) | 5 |
JSON_VALUE(’{“A”: {“B”: 3, “D”: [5, 6]}}’, ’$.A.D.1’) | 6 |
JSON_VALUE(‘1’, ’$’ RETURNING DOUBLE) | 1.0 |
JSON_VALUE(’{“A”: []}’, ’$.B’ DEFAULT ‘<null>’ ON EMPTY) | <null> |
JSON_VALUE(’{“A”: []}’, ’$.A’ ERROR ON ERROR) | error returned |
Aggregation Functions
The following functions can be used on JSON columns within aggregations.JSON_ARRAYAGG(expr)
JSON_ARRAYAGG(expr)
JSON_ARRAYAGG_DISTINCT(expr)
JSON_ARRAYAGG_DISTINCT(expr)
JSON_COLLECT_SET(expr)
JSON_COLLECT_SET(expr)
JSON_ARRAYAGG_DISTINCT.Math Functions
Scalar Functions
ABS(expr)
ABS(expr)
exprACOS(expr)
ACOS(expr)
expr as a doubleACOSF(expr)
ACOSF(expr)
expr as a floatACOSH(expr)
ACOSH(expr)
expr as a doubleACOSHF(expr)
ACOSHF(expr)
expr as a floatASIN(expr)
ASIN(expr)
expr as a doubleASINF(expr)
ASINF(expr)
expr as a floatASINH(expr)
ASINH(expr)
expr as a doubleASINHF(expr)
ASINHF(expr)
expr as a floatATAN(expr)
ATAN(expr)
expr as a doubleATANF(expr)
ATANF(expr)
expr as a floatATANH(expr)
ATANH(expr)
expr as a doubleATANHF(expr)
ATANHF(expr)
expr as a floatATAN2(x, y)
ATAN2(x, y)
ATAN2F(x, y)
ATAN2F(x, y)
ATN2(x, y)
ATN2(x, y)
ATAN2ATN2F(x, y)
ATN2F(x, y)
ATAN2FCBRT(expr)
CBRT(expr)
expr as a doubleCBRTF(expr)
CBRTF(expr)
expr as a floatCEIL(expr)
CEIL(expr)
CEILINGCEILING(expr)
CEILING(expr)
expr up to the next highest integerCOS(expr)
COS(expr)
expr as a doubleCOSF(expr)
COSF(expr)
expr as a floatCOSH(expr)
COSH(expr)
expr as a doubleCOSHF(expr)
COSHF(expr)
expr as a floatCOT(expr)
COT(expr)
expr as a doubleCOTF(expr)
COTF(expr)
expr as a floatDEGREES(expr)
DEGREES(expr)
expr (in radians) to degrees as a doubleDEGREESF(expr)
DEGREESF(expr)
expr (in radians) to degrees as a floatDIVZ(a, b, c)
DIVZ(a, b, c)
a / b unless b == 0, in which case it returns cEXP(expr)
EXP(expr)
expr as a doubleEXPF(expr)
EXPF(expr)
expr as a floatFLOOR(expr)
FLOOR(expr)
expr down to the next lowest integerGREATER(expr_a, expr_b)
GREATER(expr_a, expr_b)
expr_a and expr_b has the larger value, based on typed
comparisonHYPOT(x, y)
HYPOT(x, y)
x and y as a doubleHYPOTF(x, y)
HYPOTF(x, y)
x and y as a floatIFERROR(expr, val)
IFERROR(expr, val)
IF_ERROR(expr, val)IFINF(expr, val)
IFINF(expr, val)
IF_INF(expr, val)IFINFINITY(expr, val)
IFINFINITY(expr, val)
IF_INF(expr, val)IFNAN(expr, val)
IFNAN(expr, val)
IF_NAN(expr, val)IF_ERROR(expr, val)
IF_ERROR(expr, val)
expr, and if it resolves to infinity or
NaN, return valExample:| Function Call | Result |
|---|---|
IF_ERROR((double(10)/0), 1) | 1.0 |
IF_ERROR(log(-1), 1) | 1.0 |
IF_INF(expr, val)
IF_INF(expr, val)
expr, and if it resolves to infinity,
return valExample:| Function Call | Result |
|---|---|
IF_INF((double(10)/0), 999) | 999.0 |
IF_INF(log(-1), 999) | NaN |
IF_INFINITY(expr, val)
IF_INFINITY(expr, val)
IF_INF(expr, val)IF_NAN(expr, val)
IF_NAN(expr, val)
expr, and if it resolves to NaN,
return valExample:| Function Call | Result |
|---|---|
IF_NAN((double(10)/0), -1) | Infinity |
IF_NAN(log(-1), -1) | -1.0 |
ISINFINITY(expr)
ISINFINITY(expr)
1 (true) if expr is infinity by IEEE standard; otherwise, returns
0 (false)IS_INFINITY(expr)
IS_INFINITY(expr)
ISINFINITYISNAN(expr)
ISNAN(expr)
1 (true) if expr is not a number by IEEE standard; otherwise, returns
0 (false)IS_NAN(expr)
IS_NAN(expr)
ISNANISNUMERIC(expr)
ISNUMERIC(expr)
1 (true) if expr is a number by IEEE standard; otherwise, returns
0 (false)IS_NUMERIC(expr)
IS_NUMERIC(expr)
ISNUMERICLDEXP(x, exp)
LDEXP(x, exp)
x * 2exp as a doubleLDEXPF(x, exp)
LDEXPF(x, exp)
x * 2exp as a floatLESSER(expr_a, expr_b)
LESSER(expr_a, expr_b)
expr_a and expr_b has the smaller value, based on typed
comparisonLN(expr)
LN(expr)
expr as a doubleLNF(expr)
LNF(expr)
expr as a floatLOG(expr)
LOG(expr)
LNLOG10(expr)
LOG10(expr)
expr as a doubleLOG10F(expr)
LOG10F(expr)
expr as a floatLOG1P(expr)
LOG1P(expr)
expr as a doubleLOG1PF(expr)
LOG1PF(expr)
expr as a floatLOG2(expr)
LOG2(expr)
expr as a doubleLOG2F(expr)
LOG2F(expr)
expr as a floatLOGF(expr)
LOGF(expr)
LNFMAX_CONSECUTIVE_BITS(expr)
MAX_CONSECUTIVE_BITS(expr)
1 bits in the integer
exprMOD(dividend, divisor)
MOD(dividend, divisor)
dividend by divisorNEXT_AFTER(expr[, target])
NEXT_AFTER(expr[, target])
expr in the direction of target, incrementing expr
if target is greater, decrementing if lesser. The default
value of target is MAX_DOUBLE (always increments when
omitted). The return type matches the input (float or double).NEXT_BEFORE(expr)
NEXT_BEFORE(expr)
expr. The return type matches the input (float or double).PI()
PI()
POW(base, exponent)
POW(base, exponent)
POWERPOWF(base, exponent)
POWF(base, exponent)
POWERFPOWER(base, exponent)
POWER(base, exponent)
base raised to the power of exponent as a doublePOWERF(base, exponent)
POWERF(base, exponent)
base raised to the power of exponent as a floatRADIANS(expr)
RADIANS(expr)
expr (in degrees) to radians as a doubleRADIANSF(expr)
RADIANSF(expr)
expr (in degrees) to radians as a floatRAND([seed])
RAND([seed])
seedREGR_VALX(y, x)
REGR_VALX(y, x)
y is NULL; otherwise, returns xREGR_VALY(y, x)
REGR_VALY(y, x)
x is NULL; otherwise, returns yROUND(expr[, scale])
ROUND(expr[, scale])
expr to the nearest decimal number with scale
decimal places when scale is a positive number; rounds to
the nearest number such that the result has -(scale) zeros
to the left of the decimal point when scale is negative; use
scale of 0 to round to the nearest integer.The default value of scale is 0.Examples:| Function Call | Result |
|---|---|
ROUND(12345.678) | 12346 |
ROUND(12345.678, 2) | 12345.68 |
ROUND(12345.678, 0) | 12346 |
ROUND(12345.678, -2) | 12300 |
SIGN(expr)
SIGN(expr)
| Expression Value | Result |
|---|---|
| positive | 1 |
| zero | 0 |
| negative | -1 |
SIN(expr)
SIN(expr)
expr as a doubleSINF(expr)
SINF(expr)
expr as a floatSINH(expr)
SINH(expr)
expr as a doubleSINHF(expr)
SINHF(expr)
expr as a floatSQRT(expr)
SQRT(expr)
expr as a doubleSQRTF(expr)
SQRTF(expr)
expr as a floatTAN(expr)
TAN(expr)
expr as a doubleTANF(expr)
TANF(expr)
expr as a floatTANH(expr)
TANH(expr)
expr as a doubleTANHF(expr)
TANHF(expr)
expr as a floatTRUNCATE(expr[, scale])
TRUNCATE(expr[, scale])
expr down to the nearest decimal number with
scale decimal places when scale is a positive number;
rounds down to the nearest number such that the result has
-(scale) zeros to the left of the decimal point when
scale is negative; use scale of 0 to round down to
the nearest integer.The default value of scale is 0.Examples:| Function Call | Result |
|---|---|
TRUNCATE(12345.678) | 12345 |
TRUNCATE(12345.678, 2) | 12345.67 |
TRUNCATE(12345.678, 0) | 12345 |
TRUNCATE(12345.678, -2) | 12300 |
WIDTH_BUCKET(expr, min, max, count)
WIDTH_BUCKET(expr, min, max, count)
count equal intervals (buckets) within the range of min &
max, and puts the value of expr into one of those buckets, where the value is
greater than or equal to the minimum value of the bucket and less than the maximum
value of the bucket. Returns the 1-based number of the bucket into which the value
of expr fell. For values smaller than min, 0 is returned; for values
greater than or equal to max, count + 1 is returned. Examples:In the following examples, a set of 5 equal buckets are defined between 0 and
10 (0-2, 2-4, 4-6, 6-8, & 8-10), and various values are bucketed using
that set.| Function Call | Result |
|---|---|
WIDTH_BUCKET(-1, 0, 10, 5) | 0 |
WIDTH_BUCKET(0, 0, 10, 5) | 1 |
WIDTH_BUCKET(5, 0, 10, 5) | 3 |
WIDTH_BUCKET(10, 0, 10, 5) | 6 |
WIDTH_BUCKET(11, 0, 10, 5) | 6 |
Aggregate Functions
APPROX_COUNT_DISTINCT(expr)
APPROX_COUNT_DISTINCT(expr)
expr; this is faster to calculate than COUNT_DISTINCT but is only an approximationAPPROX_MEDIAN(expr)
APPROX_MEDIAN(expr)
expr; the result should be within about 2% of the true median value. This is equivalent to issuing
APPROX_PERCENTILE(expr, 50).APPROX_PERCENTILE(expr, p)
APPROX_PERCENTILE(expr, p)
expr; p should be a value between 0.0 and 100.0. APPROX_PERCENTILE(expr, 50) will return
the approximate median of expr.AVG(expr)
AVG(expr)
exprCORR(expr1, expr2)
CORR(expr1, expr2)
expr1 and expr2CORRELATION(expr1, expr2)
CORRELATION(expr1, expr2)
CORRCORRCOEF(expr1, expr2)
CORRCOEF(expr1, expr2)
CORRCOUNT(expr)
COUNT(expr)
expr; use * to count all values within an aggregation group or over an entire tableCOUNT_DISTINCT(expr)
COUNT_DISTINCT(expr)
exprCOV(expr1, expr2)
COV(expr1, expr2)
COVAR_POPCOVAR(expr1, expr2)
COVAR(expr1, expr2)
COVAR_POPCOVARIANCE(expr1, expr2)
COVARIANCE(expr1, expr2)
COVAR_POPCOVAR_POP(expr1, expr2)
COVAR_POP(expr1, expr2)
expr1 and expr2COVAR_SAMP(expr1, expr2)
COVAR_SAMP(expr1, expr2)
expr1 and expr2KURT(expr)
KURT(expr)
KURTOSIS_POPKURTOSIS(expr)
KURTOSIS(expr)
KURTOSIS_POPKURTOSIS_POP(expr)
KURTOSIS_POP(expr)
exprKURTOSIS_SAMP(expr)
KURTOSIS_SAMP(expr)
exprKURT_POP(expr)
KURT_POP(expr)
KURTOSIS_POPKURT_SAMP(expr)
KURT_SAMP(expr)
KURTOSIS_SAMPMAX(expr)
MAX(expr)
exprMEAN(expr)
MEAN(expr)
AVGMIN(expr)
MIN(expr)
exprPRODUCT(expr)
PRODUCT(expr)
exprREGR_AVGX(y, x)
REGR_AVGX(y, x)
SUM(x)/N) of the line determined by computing a least-squares-fit linear regression over the given (X, Y)
pairsREGR_AVGY(y, x)
REGR_AVGY(y, x)
SUM(y)/N) of the line determined by computing a least-squares-fit linear regression over the given (X, Y)
pairsREGR_COUNT(y, x)
REGR_COUNT(y, x)
REGR_INTERCEPT(y, x)
REGR_INTERCEPT(y, x)
REGR_R2(y, x)
REGR_R2(y, x)
REGR_SLOPE(y, x)
REGR_SLOPE(y, x)
REGR_SXX(y, x)
REGR_SXX(y, x)
SUM(x^2) - SUM(x)^2/N) of the line determined by computing a least-squares-fit linear regression
over the given (X, Y) pairsREGR_SXY(y, x)
REGR_SXY(y, x)
SUM(x * y) - SUM(x) * SUM(y)/N) of the line determined by computing a
least-squares-fit linear regression over the given (X, Y) pairsREGR_SYY(y, x)
REGR_SYY(y, x)
SUM(y^2) - SUM(y)^2/N) of the line determined by computing a least-squares-fit linear regression
over the given (X, Y) pairsSKEW(expr)
SKEW(expr)
SKEWNESS_POPSKEWNESS(expr)
SKEWNESS(expr)
SKEWNESS_POPSKEWNESS_POP(expr)
SKEWNESS_POP(expr)
exprSKEWNESS_SAMP(expr)
SKEWNESS_SAMP(expr)
exprSKEW_POP(expr)
SKEW_POP(expr)
SKEWNESS_POPSKEW_SAMP(expr)
SKEW_SAMP(expr)
SKEWNESS_SAMPSTDDEV(expr)
STDDEV(expr)
expr (i.e. the denominator is N)STDDEV_POP(expr)
STDDEV_POP(expr)
expr (i.e. the denominator is N)STDDEV_SAMP(expr)
STDDEV_SAMP(expr)
expr (i.e. the denominator is N-1)SUM(expr)
SUM(expr)
exprVAR(expr)
VAR(expr)
expr (i.e. the denominator is N)VAR_POP(expr)
VAR_POP(expr)
expr (i.e. the denominator is N)VAR_SAMP(expr)
VAR_SAMP(expr)
expr (i.e. the denominator is N-1)VARIANCE(expr)
VARIANCE(expr)
VARVARIANCE_POP(expr)
VARIANCE_POP(expr)
VAR_POPVARIANCE_SAMP(expr)
VARIANCE_SAMP(expr)
VAR_SAMPNull Functions
Some of the following null functions require parameters to be of convertible data types. Note that limited-width (charN) & unlimited-width (non-charN) string types are not convertible.COALESCE(expr_a, ..., expr_N)
COALESCE(expr_a, ..., expr_N)
expr_a and ending
with expr_N. If all are null, then null
is returned. All expressions should be of the
same or convertible data type.IFNULL(expr_a, expr_b)
IFNULL(expr_a, expr_b)
expr_a if it is not null; otherwise,
returns expr_b. Both should be of the same or
convertible data type. See
Short-Circuiting for error-checking
details.IS_NULL(expr)
IS_NULL(expr)
1 if expr is null; otherwise,
returns 0ISNULL(expr)
ISNULL(expr)
IS_NULL(expr)NULLIF(expr_a, expr_b)
NULLIF(expr_a, expr_b)
expr_a equals expr_b;
otherwise, returns the value of expr_a; both
expressions should be of the same or convertible
data type.NVL(expr_a, expr_b)
NVL(expr_a, expr_b)
IFNULLNVL2(expr, value_if_not_null, value_if_null)
NVL2(expr, value_if_not_null, value_if_null)
expr: if not null, returns
value_if_not_null; if null, returns
value_if_null. Both value_if_not_null &
value_if_null should be of the same data type
as expr or implicitly convertible; see
Short-Circuiting for error-checking
details.REMOVE_NULLABLE(expr)
REMOVE_NULLABLE(expr)
ZEROIFNULLZEROIFNULL(expr)
ZEROIFNULL(expr)
0 if numeric
column, an empty string if charN column, etc.).
Also removes the nullable
column property if used
to calculate a derived column.Record Distribution Functions
Record distribution functions provide a means to locate any database record within the memory processing hierarchy; and through aggregating the results, determine the distribution of records across the cluster.KI_CHUNK()
KI_CHUNK()
KI_CHUNK_ID()
KI_CHUNK_ID()
KI_CHUNK_MAX(col)
KI_CHUNK_MAX(col)
KI_CHUNK_MIN(col)
KI_CHUNK_MIN(col)
KI_CHUNK_OFFSET()
KI_CHUNK_OFFSET()
KI_PARTITION()
KI_PARTITION()
KI_RANK()
KI_RANK()
KI_TOM()
KI_TOM()
example.stocks table across the nodes of the cluster.
KI_PARTITION() can be added to the query to also
the distribution across partitions, and for clusters with more than 1 TOM per
rank (1 TOM/rank is the default), KI_TOM() can be added. To see chunk-level
distribution, use KI_CHUNK().
String Functions
There are four different types of string functions:Scalar Functions
ASCII(expr)
ASCII(expr)
exprBIN(expr[, minimum_digits])
BIN(expr[, minimum_digits])
expr into a binary string
representation. Use optional minimum_digits to add leading 0s
when needed; defaults to 1.Examples:| Function Call | Result |
|---|---|
BIN(42) | ‘101010’ |
BIN(42, 8) | ‘00101010’ |
CHAR(expr)
CHAR(expr)
expr in the
range [ 0 - 127 ]CONCAT(expr_a, expr_b)
CONCAT(expr_a, expr_b)
expr_a & expr_b; use nested
CONCAT calls to concatenate more than two stringsCONCAT will be a
VARCHAR(N) field big enough to hold the concatenated
fields, e.g., concatenating a VARCHAR(32) column and a
VARCHAR(64) column will result in a VARCHAR(128)
column. Columns of type VARCHAR(256) used with
CONCAT will result in a VARCHAR(256) column,
truncated at 256 characters.| Function Call | Result |
|---|---|
CONCAT(CONCAT(‘ABC’,‘123’),’!’) | ABC123! |
’ABC’ || ‘123’ || ’!’ | ABC123! |
CONCAT_TRUNCATE(expr_a, expr_b)
CONCAT_TRUNCATE(expr_a, expr_b)
expr_a and expr_b, truncated at
the maximum size of the larger of expr_a and expr_b.
For data columns, the size is explicit; for string constants, the size
will be the smallest charN type that can hold the constant string.CONCAT_TRUNCATE will not work if any parameter is an
unrestricted-width string.| Function Call | Result |
|---|---|
CONCAT_TRUNCATE(‘ABC123’,’!’) | ABC123! |
CONCAT_TRUNCATE(‘AB’,‘CDE’) | ABCD (char4 is the minimum size required to hold the CDE value, so the result is truncated at 4 characters) |
CONCAT_TRUNCATE(‘ABCD1234’,‘DEFG’) | ABCD1234 (an 8-character string is the minimum size required to hold the ABCD1234 value, so no characters can be appended) |
CONTAINS(match, expr)
CONTAINS(match, expr)
1 if expr contains match by
string-literal comparison; otherwise, returns 0CONV(expr, from_base, to_base)
CONV(expr, from_base, to_base)
expr string from one
numeric base to another. Base parameters may be [2 - 36].
Binary, octal and hexadecimal strings may have an optional prefix.Examples:| Function Call | Result |
|---|---|
CONV(‘42’, 10, 16) | ‘2A’ |
CONV(‘2a’, 16, 10) | ‘42’ |
CONV(‘11’, 2, 10) | ‘3’ |
CONV(‘0o52’, 8, 2) | ‘101010’ |
DEC2HEX(expr[, minimum_digits])
DEC2HEX(expr[, minimum_digits])
HEXDIFFERENCE(expr_a, expr_b)
DIFFERENCE(expr_a, expr_b)
0 and 4 that represents the difference
between the sounds of expr_a and expr_b based on the
SOUNDEX() value of the strings—a value of 4 is the best
possible sound matchEDIT_DISTANCE(expr_a, expr_b)
EDIT_DISTANCE(expr_a, expr_b)
expr_a and
expr_b; the lower the value, the more similar the two strings areENDS_WITH(match, expr)
ENDS_WITH(match, expr)
1 if expr ends with match by
string-literal comparison; otherwise, returns 0FROM_HEX(expr)
FROM_HEX(expr)
UNHEXHEX(expr[, minimum_digits])
HEX(expr[, minimum_digits])
expr into a hexadecimal string
representation. Use optional minimum_digits to add leading 0s
when needed; defaults to 1.Examples:| Function Call | Result |
|---|---|
HEX(42) | ‘2A’ |
HEX(42, 8) | ‘0000002A’ |
HEX2DEC(expr)
HEX2DEC(expr)
UNHEXINITCAP(expr)
INITCAP(expr)
expr with the first letter of each word in uppercaseIPV4_PART(expr, part_num)
IPV4_PART(expr, part_num)
expr at the position
specified by part_num. Valid part_num values are constants
from 1 to 4.Examples:| Function Call | Result |
|---|---|
IPV4_PART(‘12.34.56.78’, 1) | 12 |
IPV4_PART(‘12.34.56.78’, 4) | 78 |
IS_IPV4(expr)
IS_IPV4(expr)
1 if expr is an IPV4 address; returns 0 otherwiseISIPV4(expr)
ISIPV4(expr)
IS_IPV4LCASE(expr)
LCASE(expr)
expr to lowercaseLEFT(expr, num_bytes)
LEFT(expr, num_bytes)
num_bytes bytes from exprLEN(expr)
LEN(expr)
LENGTHLENGTH(expr)
LENGTH(expr)
exprLOCATE(match, expr[, start_pos])
LOCATE(match, expr[, start_pos])
match in
expr, starting from position 1 or start_pos (if
specified). If match can’t be found or start_pos is
outside the range of letters in expr, a 0 is returned.LOWER(expr)
LOWER(expr)
LCASELPAD(expr, length[, pad])
LPAD(expr, length[, pad])
expr string with the pad string
to the given length of bytes. If expr is longer than
length, the return value is shortened to length bytes. If
length is larger than 256, it will be truncated to 256 bytes. The
default padding character is a space.Examples:| Function Call | Result |
|---|---|
LPAD(‘test’, 9, ‘pad’) | padpatest |
LPAD(‘test’, 3, ‘pad’) | tes |
LTRIM(expr)
LTRIM(expr)
exprOCT(expr[, minimum_digits])
OCT(expr[, minimum_digits])
expr into an octal (base 8)
string representation. Use optional minimum_digits to add leading
0s when needed; defaults to 1.Examples:| Function Call | Result |
|---|---|
OCT(42) | ‘52’ |
OCT(42, 8) | ‘00000052’ |
POSITION(match IN expr)
POSITION(match IN expr)
match in
expr, starting from position 1. If match can’t be
found, a 0 is returned.REGEXP_COUNT (expr, regex[, position [, mode]])
REGEXP_COUNT (expr, regex[, position [, mode]])
regex pattern is
matched in expr. Matches do not overlap, so the start of a future
match must start after the end of the previous match.The regex parameter is the regular expression to try to match.
It must be a string-literal with 256 characters or fewer. Generally,
POSIX-compliant regular expressions are supported for regex.
The escape character used to match wildcards in the expr literally
is \. See REGEXP_LIKE for more regular expression examples.The optional position parameter specifies where to start searching
in expr for the first match. The first character in the string
has a position of 1 (the default).The optional mode parameter is a string which can be empty
(the default) for the default behavior. See REGEXP_LIKE for the
list of supported mode flags.Examples of REGEXP_COUNT:| Function Call | Result |
|---|---|
REGEXP_COUNT(‘abababab’, ‘abab’) | 2 |
REGEXP_COUNT(‘abababab’, ‘abab’, 2) | 1 |
REGEXP_COUNT(‘don”t’, ‘DON”T’, 1, ‘i’) | 1 |
REGEXP_INSTR (expr, regex [, position [, occurrence [, begin_end [, mode [,group]]]]])
REGEXP_INSTR (expr, regex [, position [, occurrence [, begin_end [, mode [,group]]]]])
expr where a regex
match is found. If no match is found, 0 is returned.The regex parameter is the regular expression to try to match.
It must be a string-literal with 256 characters or fewer. Generally,
POSIX-compliant regular expressions are supported for regex.
The escape character used to match wildcards in the expr literally
is \. See REGEXP_LIKE for more regular expression examples.The optional position parameter specifies where to start searching
in expr for the first match. The first character in the string
has a position of 1 (the default).The optional occurrence parameter specifies which occurrence of
the regex match is desired. For example, 2 would return the
second occurrence of regex in expr. Matches do not overlap,
so the start of a future match must start after the end of the
previous match.The optional begin_end parameter specifies if the beginning or
ending position is desired. Use 0 (the default) for the beginning
of the match and use 1 for the position after the end of the
match.The optional mode parameter is a string which can be empty
(the default) for the default behavior. See REGEXP_LIKE for the
list of supported mode flags.The optional group parameter specifies which regular expression
group’s (i.e., parentheses inside regex) beginning/ending position
to return. The default of 0 uses the entire matched expression,
while a group of 1 through 9 corresponds to the 1st group
up through the 9th group of the match.Examples of REGEXP_INSTR:| Function Call | Result |
|---|---|
REGEXP_INSTR(‘abcdefg’, ‘bc’) | 2 |
REGEXP_INSTR(‘abcdefg’, ‘ab’, 2) | 0 |
REGEXP_INSTR(‘abcabc’, ‘a’, 1, 2) | 4 |
REGEXP_INSTR(‘abcabc’, ‘abc’, 1, 1, 1) | 4 |
REGEXP_INSTR(‘abcabc’, ‘B C’, 1, 1, 0, ‘ix’) | 2 |
REGEXP_INSTR(‘abcdefg’, ‘(C(.(.)))’, 1, 1, 0, ‘i’, 3) | 5 |
REGEXP_LIKE(expr, regex[, mode])
REGEXP_LIKE(expr, regex[, mode])
expr matches the given regex. Generally,
POSIX-compliant regular expressions are supported.The optional mode parameter is a string which can be empty
(the default) for the default behavior. It can contain the following
letters for the associated optional modified behaviors:| Letter | Meaning |
|---|---|
i | Case-insensitive matches |
m | Treat input as multiple lines so ^ and $ match around newlines and not just the beginning and ending of the string |
n | Allows . to also match a newline character |
x | Ignore any whitespace (e.g., spaces) in regex |
expr literally
is \.regex can match the expr partially. To perform
full matches, ^ and $ can be used to match the
start and end of expr, respectively.| Function Call | Match Type |
|---|---|
REGEXP_LIKE(‘partial’, ‘part’) | Partial |
REGEXP_LIKE(‘Case’, ‘cAsE’, ‘i’) | Case-insensitive |
REGEXP_LIKE(‘dot’, ‘d.t’) | Any character |
REGEXP_LIKE(‘range’, ‘ra[a-z]ge’) | Character range |
REGEXP_LIKE(‘zeroorone’, ‘z?zer(oor)?one’) | 0 or 1 token |
REGEXP_LIKE(‘zeroormore’, ‘z*zer([om]or)*e’) | 0 or more tokens |
REGEXP_LIKE(‘oneormore’, ‘o+n([em]or)+e’) | 1 or more tokens |
REGEXP_LIKE(‘A to Z’, ‘^A.*Z$‘) | Begin/End |
REGEXP_LIKE(‘41ph4Num’, ’^[[:alnum:]]+$‘) | Character class |
REGEXP_LIKE(‘Escape?’, ‘Escape?’) | Escape wildcard |
REGEXP_MATCH(expr, regex[, options])
REGEXP_MATCH(expr, regex[, options])
REGEXP_LIKEREGEXP_REPLACE (expr, regex [, replace [, position [, occurrence [, mode]]]])
REGEXP_REPLACE (expr, regex [, replace [, position [, occurrence [, mode]]]])
expr string after replacing regex matches with the
replace string parameter.The regex parameter is the regular expression to try to match.
It must be a string-literal with 256 characters or fewer. Generally,
POSIX-compliant regular expressions are supported for regex.
The escape character used to match wildcards in the expr literally
is \. See REGEXP_LIKE for more regular expression examples.The replace parameter is the optional text with which to replace
each match of regex in expr. The default is an empty string,
which will simply remove the specified occurrences of regex in
expr. A replace of \0 will insert the entire matched
expression, while a replace of \1 through \9 will use the
corresponding matched grouping (parentheses inside regex) as the
replacement text.The optional position parameter specifies where to start searching
in expr for the first match. The first character in the string
has a position of 1 (the default).The optional occurrence parameter specifies which occurrence of
the regex match to replace. For example, 2 would only replace
the second occurrence of regex in expr. Matches do not
overlap, so the start of a future match must start after the end of
the previous match. Use 0 (the default) to replace all
occurrences.The optional mode parameter is a string which can be empty
(the default) for the default behavior. See REGEXP_LIKE for the
list of supported mode flags.Examples of REGEXP_REPLACE:| Function Call | Result |
|---|---|
REGEXP_REPLACE(‘abc’, ‘b’) | ac |
REGEXP_REPLACE(‘abc’, ‘b.’, ‘x’) | ax |
REGEXP_REPLACE(‘abcd’, ’.’, ‘x’, 3, 1) | abxd |
REGEXP_REPLACE(‘abcd’, ‘(b(.))’, ’-\2-’) | a-c-d |
REGEXP_SUBSTR (expr, regex [, position [, occurrence [, mode [,group]]]])
REGEXP_SUBSTR (expr, regex [, position [, occurrence [, mode [,group]]]])
expr string that matched regex.
An empty string is returned if no match is found.The regex parameter is the regular expression to try to match.
It must be a string-literal with 256 characters or fewer. Generally,
POSIX-compliant regular expressions are supported for regex.
The escape character used to match wildcards in the expr literally
is \. See REGEXP_LIKE for more regular expression examples.The optional position parameter specifies where to start searching
in expr for the first match. The first character in the string
has a position of 1 (the default).The optional occurrence parameter specifies which occurrence of
the regex match is desired. For example, 2 would return the
second occurrence of regex in expr. Matches do not overlap,
so the start of a future match must start after the end of the
previous match.The optional mode parameter is a string which can be empty
(the default) for the default behavior. See REGEXP_LIKE for the
list of supported mode flags.The optional group parameter specifies which regular expression
grouping (i.e., parentheses inside regex) to use. The default of
0 uses the entire matched expression, while a group of 1
through 9 corresponds to the 1st group up through the 9th group of
the match.Examples of REGEXP_SUBSTR:| Function Call | Result |
|---|---|
REGEXP_SUBSTR(‘abcdefg’, ‘b.’) | bc |
REGEXP_SUBSTR(‘abcadeafghij’, ‘a…’, 2, 1) | adea |
REGEXP_SUBSTR(‘abcadeafghij’, ‘a…’, 1, 2) | afgh |
REGEXP_SUBSTR(‘abcdefg’, ‘(C(.(.)))’, 1, 1, ‘i’, 3) | e |
REPLACE(expr, match, repl)
REPLACE(expr, match, repl)
match in expr with replREPLACE_CHAR(expr, match, repl)
REPLACE_CHAR(expr, match, repl)
match in
expr with the single-byte character replREPLACE_TRUNCATE(expr, match, repl)
REPLACE_TRUNCATE(expr, match, repl)
match in expr with repl, and
then truncates the resulting string at 256 bytes if it is longer than
thatREPLACE_TRUNCATE will not work if any parameter is an
unrestricted-width string.REVERSE(expr)
REVERSE(expr)
expr with the order of bytes reversed.Examples:| Function Call | Result |
|---|---|
REVERSE(‘Reverse’) | esreveR |
REVERSE(‘Was it a bat I saw?’) | ?was I tab a ti saW |
RIGHT(expr, num_bytes)
RIGHT(expr, num_bytes)
num_bytes bytes from exprRPAD(expr, length, pad)
RPAD(expr, length, pad)
expr string with the pad string
to the given length of bytes. If expr is longer than
length, the return value is shortened to length bytes. If
length is larger than 256, it will be truncated to 256 bytes. The
default padding character is a space.Examples:| Function Call | Result |
|---|---|
RPAD(‘test’, 9, ‘pad’) | testpadpa |
RPAD(‘test’, 3, ‘pad’) | tes |
RTRIM(expr)
RTRIM(expr)
exprSOUNDEX(expr)
SOUNDEX(expr)
expr. Only the first word in the
string will be considered in the calculation.SPACE(n)
SPACE(n)
n space characters. The value of
n can only be within the range of 0-256.SPLIT(expr, delim, group_num)
SPLIT(expr, delim, group_num)
expr into groups delimited by the delim single-byte
character and returns the group_num split group. If group_num
is positive, groups will be counted from the beginning of expr; if
negative, groups will be counted from the end of expr going
backwards. Two consecutive delimiters will result in an empty string
being added to the list of selectable groups. If no instances of
delim exist in expr, the entire string is available at group
1 (and -1). Group 0 returns nothing.Examples:| Function Call | Result |
|---|---|
SPLIT(‘apple’, ‘p’, 1) | a |
SPLIT(‘apple’, ‘p’, 2) | <empty string> |
SPLIT(‘apple’, ‘p’, -1) | le |
STARTS_WITH(match, expr)
STARTS_WITH(match, expr)
1 if expr starts with match by
string-literal comparison; otherwise, returns 0STRCMP(expr_a, expr_b)
STRCMP(expr_a, expr_b)
expr_a to expr_b in a lexicographical sort| Situation | Result |
|---|---|
expr_a and expr_b are the same | 0 |
expr_a comes before expr_b, lexicographically | -1 |
expr_a comes after expr_b, lexicographically | 1 |
SUBSTR(expr, start_pos[, num_chars])
SUBSTR(expr, start_pos[, num_chars])
SUBSTRINGSUBSTRING(expr, start_pos[, num_bytes])
SUBSTRING(expr, start_pos[, num_bytes])
num_bytes bytes from the expr, starting at the 1-based
start_pos byte. If num_bytes is not specified, all bytes
after start_pos will be returned.Examples:| Function Call | Result |
|---|---|
SUBSTRING(‘banana’, 3) | nana |
SUBSTRING(‘banana’, 3, 2) | na |
TO_HEX(expr[, minimum_digits])
TO_HEX(expr[, minimum_digits])
HEXTRIM(expr)
TRIM(expr)
exprUCASE(expr)
UCASE(expr)
expr to uppercaseUNHEX(expr)
UNHEX(expr)
expr into a (decimal) number.Examples:| Function Call | Result |
|---|---|
UNHEX(‘42’) | 66 |
UNHEX(‘1A’) | 26 |
UNHEX(‘1a’) | 26 |
UPPER(expr)
UPPER(expr)
UCASEAggregation Functions
The following functions can be used on string columns within aggregations. These functions can be used to convert string column values into delimited lists of those values.STRING_AGG(expr[, delim])
STRING_AGG(expr[, delim])
STRING_AGG_DISTINCT(expr[, delim])
STRING_AGG_DISTINCT(expr[, delim])
LIKE / ILIKE
Simple pattern-matching capability is provided through the use of theLIKE and ILIKE
clauses, for string columns. LIKE is case-sensitive,
while ILIKE is case-insensitive.
expr does (or does
NOT) match the string value of match. The match is a string literal
one, with the following exceptions:
%matches any string of 0 or more characters_matches any single character[<character_set>]matches any single character listed in the set. Thecharacter_setmay contain ranges using a dash (-). Acharacter_setstarting with^will match any character not in the specified set.
ESCAPE clause to specify
an escape character. The escape character is used to match special characters
in the expr literally. For example, ~% will match the % character
if ~ is the escape character.
To search for employees whose last name starts with C, ends with a, and has
exactly five letters:
~ to escape the underscore:
FILTER_BY_STRING
TheFILTER_BY_STRING table function allows for several types of pattern
matching for fixed-width string columns
(VARCHAR(1) - VARCHAR(256)), as well as
full text search capability for all
string columns with the TEXT_SEARCH
column property. Its features are based
on the /filter/bystring endpoint.
The basic form of the FILTER_BY_STRING function when called in a SELECT
statement follows.
FILTER_BY_STRING function when called in an
EXECUTE FUNCTION statement follows. When called this way, the results are
saved in the specified view.
TABLE_NAME
TABLE_NAME
INPUT_TABLE function.To perform a string filter on a column in the customer table, pass the name of the table to
INPUT_TABLE:INPUT_TABLE:VIEW_NAME
VIEW_NAME
EXECUTE FUNCTION syntax.COLUMN_NAMES
COLUMN_NAMES
search filter MODE.MODE
MODE
| Mode | Description |
|---|---|
contains | Partial substring match (not accelerated). If the column is a string type (non-charN) and the number of records is too large, it will return 0. |
equals | Exact whole-string match (accelerated). |
regex | Full regular expression search (not accelerated). If the column is a string type (non-charN) and the number of records is too large, it will return 0. |
search | Full text search with wildcards and boolean operators, for string columns (VARCHAR) that have the TEXT_SEARCH column property applied. See Full Text Search for syntax & grammar detail. Omit the COLUMN_NAMES parameter when using this MODE. All text-searchable string columns will be searched. Also, only a table name can be used for TABLE_NAME—a query cannot be used. |
starts_with | Match strings that start with the given expression (not accelerated). If the column is a string type (non-charN) and the number of records is too large, it will return 0. |
EXPRESSION
EXPRESSION
MODE selected, to use in filtering string columnsOPTIONS
OPTIONS
<key> = '<value>' assignments to the KV_PAIRS function; e.g.:| Option | Description |
|---|---|
case_sensitive | If true, the filter will be case-sensitive; if false, case-insensitive. Not applicable when MODE is search. |
User/Security Functions
CURRENT_SCHEMA()
CURRENT_SCHEMA()
CURRENT_USER()
CURRENT_USER()
USERHASH(column[, seed])
HASH(column[, seed])
column, using the given seed; default seed is 0IS_MEMBER(role[, user/role])
IS_MEMBER(role[, user/role])
user/role,
if specified) has been assigned the given role, either
directly or indirectly:| Situation | Result |
|---|---|
Current user (or given user/role) has been granted role | true |
Current user (or given user/role) has not been granted role | false |
Role role does not exist | null |
IS_ROLEMEMBER(role[, user/role])
IS_ROLEMEMBER(role[, user/role])
IS_MEMBERMASK(expr, start, length[, char])
MASK(expr, start, length[, char])
length bytes of expr, beginning at the byte position
identified by start, with * characters (or the single-byte
character specified in char):| Function Call | Result |
|---|---|
MASK(‘Characters’, 4, 5) | Cha*****rs |
MASK(‘Characters’, 5, 2, ’#‘) | Char##ters |
NEW_UUID()
NEW_UUID()
OBFUSCATE(column[, seed])
OBFUSCATE(column[, seed])
HASHSHA256(expr)
SHA256(expr)
expr as a char64 string.SYSTEM_USER()
SYSTEM_USER()
USERUSER()
USER()
Aggregation Functions
These functions can be applied to aggregate data. They include:- Array Aggregation Functions
- Geospatial/Geometry Aggregation Functions
- JSON Aggregation Functions
- Lookup/Grouping Aggregation Functions
- Math Aggregation Functions
- String Aggregation Functions
Lookup/Grouping Functions
ARG_MAX(agg_expr, ret_expr)
ARG_MAX(agg_expr, ret_expr)
ret_expr where agg_expr is the maximum
value (e.g. ARG_MAX(cost, product_id) returns the product
ID of the highest cost product). ARG_MAX(a, b) is equivalent to
LAST(b, a).ARG_MIN(agg_expr, ret_expr)
ARG_MIN(agg_expr, ret_expr)
ret_expr where agg_expr is the minimum
value (e.g. ARG_MIN(cost, product_id) returns the product
ID of the lowest cost product). ARG_MIN(a, b) is equivalent to
FIRST(b, a).ATTR(expr)
ATTR(expr)
MIN(expr) = MAX(expr), returns expr; otherwise
*expr must resolve to a string type, and must be casted
to one, if not alreadyFIRST(ret_expr, agg_expr)
FIRST(ret_expr, agg_expr)
ret_expr where agg_expr is the minimum
value (e.g. FIRST(product_id, cost) returns the product ID
ID of the lowest cost product). FIRST(a, b) is equivalent to
ARG_MIN(b,a)GROUPING(expr)
GROUPING(expr)
expr is part of the aggregation set used to calculate the
values in a given result set row. Returns 0 if expr
is part of the row’s aggregation set, 1 if expr is not
(meaning that aggregation took place across all expr
values).For example, in a ROLLUP(A) operation, there will be two
potential rows with null in the result set for column A.
One row will contain null values of A aggregated
together, and the other will contain null, but be an
aggregation over the entire table, irrespective of A
values. In this case, GROUPING(A) will return 0 for
the null values of A aggregated together (as well as all
other grouped A values) and 1 for the row resulting
from aggregating across all A values.LAST(ret_expr, agg_expr)
LAST(ret_expr, agg_expr)
ret_expr where agg_expr is the maximum
value (e.g. LAST(product_id, cost) returns the product
ID of the highest cost product). LAST(a, b) is equivalent to
ARG_MAX(b, a).Grouping Functions
These functions can be applied to group data.ROLLUP(expr)
ROLLUP(expr)
exprCUBE(expr)
CUBE(expr)
exprGROUPING SETS(expr)
GROUPING SETS(expr)
expr, including ROLLUP() and
CUBE()ML Functions
There are two supported machine learning functions:PREDICT
ThePREDICT table function will predict the values of the dependent
variables that correspond to a given column of independent variables, using a
given base table containing “historical” values of each. This table will be
used as the basis to calculate the prediction.
To make the prediction, the slope & y-intercept of the least-squares-fit linear
equation of the base table data will be calculated. Then, that line will be
used to calculate the dependent variable for each given independent variable,
and the values of each will be returned in the result set as Y and X,
respectively.
The basic form of the PREDICT function, called within a SELECT statement
follows.
HISTORY_TABLE
HISTORY_TABLE
INPUT_TABLE:INPUT_TABLE:X_COLUMN
X_COLUMN
HISTORY_TABLE containing the independent variable that
will be used as the basis for the prediction.Y_COLUMN
Y_COLUMN
HISTORY_TABLE containing the dependent variable that
will be used as the basis for the prediction.PREDICT_ON_TABLE
PREDICT_ON_TABLE
INPUT_TABLE:INPUT_TABLE:PREDICT_ON_COLUMN
PREDICT_ON_COLUMN
PREDICT_ON_TABLE containing the independent variable
against which the prediction will be made.PREDICT_METHOD
PREDICT_METHOD
LINEAR.OUTLIERS
TheOUTLIERS table function will calculate the outliers in a given data set,
based on a specified calculation type, threshold, and partition column. The
partition column allows the data to be segmented into subsets, one per unique
partition column value, and have the outliers for each subset calculated &
determined independently from other subsets.
The basic form of the OUTLIERS function, called within a SELECT
statement follows.
DATA_TABLE
DATA_TABLE
INPUT_TABLE:INPUT_TABLE:DATA_COLUMN
DATA_COLUMN
DATA_TABLE containing the outliers to detect.PARTITION_COLUMN
PARTITION_COLUMN
DATA_TABLE containing the value to partition over, when
detecting outliers. Each unique PARTITION_COLUMN value will denote a subset of the source
data, within which outliers will be determined independently from other subsets.OUTLIER_METHOD
OUTLIER_METHOD
ZSCORE.| Method | Description |
|---|---|
ZSCORE | Z-score calculation, indicating the number of standard deviations above the mean each value within the set is. If a PARTITION_COLUMN is given, the z-score will be calculated for each subset of data corresponding to a unique PARTITION_COLUMN value. The z-score uses the following formula: |
PERCENTILE | The standard percentile calculation, performed within each PARTITION_COLUMN group (if specified). Scores will be decimals between 0, inclusive, and 100, exclusive. |
THRESHOLD_LOW
THRESHOLD_LOW
OUTLIER_METHOD used:ZSCORE- Threshold is the negative number of standard deviations to the left of the mean, beyond which outliers are found; e.g.,-3would indicate a threshold of 3 standard deviations lower than the mean.PERCENTILE- Threshold is the percentage lower than which outliers are found; e.g.,25would indicate outliers have percentile scores below 25%.
THRESHOLD_HIGH
THRESHOLD_HIGH
OUTLIER_METHOD used:ZSCORE- Threshold is the positive number of standard deviations to the right of the mean, beyond which outliers are found; e.g.,3would indicate a threshold of 3 standard deviations higher than the mean.PERCENTILE- Threshold is the percentage higher than which outliers are found; e.g.,75would indicate outliers have percentile scores above 75%.
OUTLIER_DATA
OUTLIER_DATA
OUTLIERS.| Method | Description |
|---|---|
OUTLIERS | Return only the records that are outliers. |
NON_OUTLIERS | Return only the records that are not outliers. |
ALL | Return all records. |
OUTPUT_SCORE
OUTPUT_SCORE
TRUE, the calculated score for each record will be added to the result set in a column
named OUTPUT_SCORE.Distribution Functions
Distribution functions are column expressions that affect the sharded/replicated nature of the result set of a given query. It may be necessary to force a result set to be distributed in a certain way for a subsequent operation on that result set to be performant.KI_REPLICATE()
KI_REPLICATE()
GROUP BY)KI_REPLICATE_GROUP_BY(0)
KI_REPLICATE_GROUP_BY(0)
GROUP BY)KI_MATCH_COLUMN(0)
KI_MATCH_COLUMN(0)
KI_SHARD_KEY(<column list>)
KI_SHARD_KEY(<column list>)
column list must also appear in the
SELECT list; KI_SHARD_KEY merely identifies which of the
selected columns should be used as the shard key.Sharding Example
For example, a query for all employees and their total employees managed, including employees who don’t manage anyone, could employ a UNION like this:employee table is sharded on id.
Since the first part of the UNION aggregates on manager_id, the result
will be replicated. The second part of the UNION does
no aggregation and includes the shard key in the SELECT
list; the result of this will be sharded.
Prior to Kinetica v7.0, the limitation of UNION
operations requiring that both parts of a UNION have to be distributed the
same way, would make the query fail, with the following message:
UNION to match the second
part:
KI_SHARD_KEY is used to make the selected
manager_id column the new shard key for the first part of the UNION.
Now, the shard key for the first part of the UNION (manager_id) aligns
with the shard key for the second part (id), and the query succeeds. Note
the use of KI_MATCH_COLUMN, which aligns the selected column lists on each
side of the UNION. Without this matching distribution function, the
UNION would appear to be merging three columns from the first part of the
query into two columns in the second part and would fail.
manager_id column must exist in the SELECT list in order
for the KI_SHARD_KEY function to designate it as the shard key.Predicates
Predicate are generally used within a SQLWHERE clause to query records.
They compare the values of two or more expressions; whenever a record meets
the criteria defined in a predicate clause it will be marked as eligible
to be part of the query result set. If it meets all predicate clauses defined
within a query, it will be returned in the result set.
A single predicate clause may use a simple predicate operator to compare the
values of two expressions or a more complex predicate clause form. A
compound predicate clause uses a compound predicate operator to link
together multiple predicate clauses to further refine a result set.
Unlimited-width (non-charN) strings can only be used within
equality-based predicates, e.g. =, IN, etc.
Predicate Operators
=equality!=or<>inequality<less than<=less than or equal to>greater than>=greater than or equal to
Predicate Clauses
In the following list of predicate clauses,ref_expr is the reference
expression to apply the predicate to; note that EXISTS has no reference
expression.
| Predicate Clause | Description |
|---|---|
<expr_a> <pred_op> <expr_b> | Matches records where expr_a relates to expr_b according to predicate operator pred_op. |
<ref_expr> <pred_op> ALL (<select statement>) | Matches records where the reference expression ref_expr relates to all of the results of select statement according to the predicate operator pred_op |
<ref_expr> <pred_op> ANY (<select statement>) | Matches records where the reference expression ref_expr relates to any of the results of select statement according to the predicate operator pred_op |
<ref_expr> [NOT] BETWEEN <begin_expr> AND <end_expr> | Matches records where the reference expression ref_expr is (or is NOT) between the values of begin_expr and end_expr, inclusive |
<ref_expr> [NOT] IN (<match_list>) | Matches records where the reference expression ref_expr is (or is NOT) in the match_list list of match values. The list can either be a comma-separated list of terms/expressions or the result of a SELECT statement. |
<ref_expr> IS [NOT] NULL | Matches records where the reference expression ref_expr is (or is NOT) null. |
[NOT] EXISTS (<select statement>) | Matches records where select statement returns 1 or more records. |
Compound Predicate Operators
| Predicate Operator | Description |
|---|---|
<pred_a> AND <pred_b> | Matches records where both pred_a & pred_b are true |
<pred_a> OR <pred_b> | Matches records where either pred_a or pred_b is true |
NOT <pred_b> | Matches records where pred is false |
Subqueries
Non-Correlated Subqueries
These are subqueries that are self-contained, in that they can be executed independently of the surrounding query.Correlated Subqueries
These are subqueries that depend on the values in the surrounding query, and cannot be executed independently of the surrounding query.- They cannot reference grouping columns in the parent query
- They cannot reference tables beyond the immediate outer query; i.e., a table cannot be referenced in a correlated subquery that is two or more levels of nesting deeper than it is
- They cannot contain disjunctive conditions
- They cannot be part of an
OUTER JOIN ONclause condition
Remote Queries
A remote query makes use of a data source to run a given query on the remote system referenced by that data source.Parameters
<remote query>
<remote query>
<data source name>
<data source name>
Examples
To query employees’ managers from a given remote system:Hints
Hints can be added as comments within queries, and affect just the query in which they appear. They will override the corresponding client & server settings (when such settings exist). Kinetica supports both global & scoped hints:- Scoped Hints - affect a portion of the query
- Global Hints - affect the entire query
Scoped Hints
Scoped hints may appear anywhere in the query. Scoped hints must be in a comment block in the form:KI_HINT_DELTA_TABLE
KI_HINT_DELTA_TABLE
FROM <table> clause to
which it applies, but before any table alias specified for that table.KI_HINT_GROUP_BY_PK
KI_HINT_GROUP_BY_PK
GROUP BY, and can also make
materialized views containing
grouping operations more performant.SELECT
keyword or immediately after the FROM <table> clause.KI_HINT_MATERIALIZE
KI_HINT_MATERIALIZE
WITH clause; if different WHERE
clauses are applied to the CTE, the CTE query may only have to be evaluated
once.This hint must be placed immediately after the SELECT keyword, like the
SELECT producing a join.KI_HINT_MATERIALIZE includes the functionality of
KI_HINT_NO_VIRTUAL_UNION.KI_HINT_NO_VIRTUAL_UNION
KI_HINT_NO_VIRTUAL_UNION
SELECT keyword, like
the first SELECT keyword in the union.Global Hints
Global hints may appear anywhere in the query. Global hints must be in a comment block in the form:KI_HINT_BATCH_SIZE(n)
KI_HINT_BATCH_SIZE(n)
n records. Default: 10,000.Only applicable when issuing INSERT statements.KI_HINT_CHUNK_SIZE(n)
KI_HINT_CHUNK_SIZE(n)
n records per chunk within result sets.
Suffixes of K & M can be used to represent thousands or
millions of records; e.g., 20K, 50M.KI_HINT_COST_BASED_OPTIMIZATION
KI_HINT_COST_BASED_OPTIMIZATION
sql.cost_based_optimization), they can be turned on for an individual
query using this hint.KI_HINT_DICT_PROJECTION
KI_HINT_DICT_PROJECTION
KI_HINT_DISTRIBUTED_OPERATIONS
KI_HINT_DISTRIBUTED_OPERATIONS
KI_HINT_DONT_COMBINE
KI_HINT_DONT_COMBINE
KI_HINT_GROUP_BY_FORCE_REPLICATED
KI_HINT_GROUP_BY_FORCE_REPLICATED
KI_HINT_GROUP_BY_PK
KI_HINT_GROUP_BY_PK
GROUP BY, and can also make materialized views containing grouping
operations more performant.KI_HINT_HAS_HEADER
KI_HINT_HAS_HEADER
KI_HINT_IGNORE_EXISTING_PK
KI_HINT_IGNORE_EXISTING_PK
KI_HINT_UPDATE_ON_EXISTING_PK hint is used to switch to upsert mode
for inserts or overwrite mode for updates, then this hint is ignored.KI_HINT_INDEX(column_list)
KI_HINT_INDEX(column_list)
column_list; often used with
CREATE TABLE … AS to create an index on a
persisted result set.KI_HINT_JOIN_TABLE_CHUNK_SIZE(n)
KI_HINT_JOIN_TABLE_CHUNK_SIZE(n)
n records per chunk within joins.
Suffixes of K & M can be used to represent thousands or
millions of records; e.g., 20K, 50M.KI_HINT_KEEP_TEMP_TABLES
KI_HINT_KEEP_TEMP_TABLES
KI_HINT_KEY_LOOKUP
KI_HINT_KEY_LOOKUP
KI_HINT_NO_COST_BASED_OPTIMIZATION
KI_HINT_NO_COST_BASED_OPTIMIZATION
KI_HINT_NO_DICT_PROJECTION
KI_HINT_NO_DICT_PROJECTION
KI_HINT_NO_DISTRIBUTED_OPERATIONS
KI_HINT_NO_DISTRIBUTED_OPERATIONS
KI_HINT_NO_HEADER
KI_HINT_NO_HEADER
KI_HINT_NO_JOIN_COUNT
KI_HINT_NO_JOIN_COUNT
KI_HINT_NO_LATE_MATERIALIZATION
KI_HINT_NO_LATE_MATERIALIZATION
KI_HINT_NO_NATIVE_SEMI_JOINS
KI_HINT_NO_NATIVE_SEMI_JOINS
KI_HINT_NO_PARALLEL_EXECUTION
KI_HINT_NO_PARALLEL_EXECUTION
KI_HINT_NO_PLAN_CACHE
KI_HINT_NO_PLAN_CACHE
KI_HINT_NO_QUERY_RESULT_CACHING
KI_HINT_NO_QUERY_RESULT_CACHING
KI_HINT_NO_RULE_BASED_OPTIMIZATION
KI_HINT_NO_RULE_BASED_OPTIMIZATION
KI_HINT_NO_SHADOW_CUBE
KI_HINT_NO_SHADOW_CUBE
KI_HINT_NO_SSQ_OPTIMIZATION
KI_HINT_NO_SSQ_OPTIMIZATION
KI_HINT_NO_VALIDATE_CHANGE
KI_HINT_NO_VALIDATE_CHANGE
KI_HINT_NO_VIRTUAL_UNION
KI_HINT_NO_VIRTUAL_UNION
KI_HINT_PROJECT_MATERIALIZED_VIEW
KI_HINT_PROJECT_MATERIALIZED_VIEW
KI_HINT_REPL_ASYNC
KI_HINT_REPL_ASYNC
KI_HINT_REPL_ASYNC_PARALLEL
KI_HINT_REPL_ASYNC_PARALLEL
KI_HINT_REPL_NONE
KI_HINT_REPL_NONE
KI_HINT_REPL_SYNC
KI_HINT_REPL_SYNC
KI_HINT_REPL_SYNC_PARALLEL
KI_HINT_REPL_SYNC_PARALLEL
KI_HINT_REQUEST_TIMEOUT(m)
KI_HINT_REQUEST_TIMEOUT(m)
m minutes when processing this command.KI_HINT_SAVE_UDF_STATS
KI_HINT_SAVE_UDF_STATS
KI_HINT_SERVER_SIDE_INSERT
KI_HINT_SERVER_SIDE_INSERT
KI_HINT_TRUNCATE_STRINGS
KI_HINT_TRUNCATE_STRINGS
KI_HINT_UPDATE_ON_EXISTING_PK
KI_HINT_UPDATE_ON_EXISTING_PK
- For INSERT statements, invoke an upsert scheme; any existing table record with primary key values that match those of a record being inserted will be replaced by that new record.
- For UPDATE statements, invoke an overwrite scheme;
if a record update causes the record’s primary key to match that of
another record in the same table, that other record will be removed and
the original record will remain, updated with its new primary key and any
other values from the
SETclause.
INSERT or UPDATE will be rejected and the
error handled based on the presence of the KI_HINT_IGNORE_EXISTING_PK
hint. If the specified table does not have a primary key, then this hint
will be ignored.KI_HINT_WAL_SYNC_METHOD(method)
KI_HINT_WAL_SYNC_METHOD(method)
method for a query.| Method | Description |
|---|---|
none | Disables the write-ahead log feature. |
background | WAL entries are periodically written instead of immediately after each operation. |
flush | Protects entries in the event of a database crash. |
fsync | Protects entries in the event of an OS crash. |
Testing Hints
The following global hints are intended to be used for testing. They are usually not recommended for regular use and are subject to change.KI_HINT_NO_CHUNK_SKIPPING
KI_HINT_NO_CHUNK_SKIPPING
KI_HINT_NO_CONSTANT_FOLDING
KI_HINT_NO_CONSTANT_FOLDING
KI_HINT_NO_HAVING_PUSHDOWN
KI_HINT_NO_HAVING_PUSHDOWN
HAVING clauses when planning this query.KI_HINT_NO_TRANSITIVE_SIMPLIFICATIONS
KI_HINT_NO_TRANSITIVE_SIMPLIFICATIONS
EXPLAIN
Outputs the execution plan of a given SQL statement.-
PHYSICAL- (default) outputs the physical execution plan with the following endpoint-level details per step:ID- execution step numberENDPOINT- name of native API endpoint calledINPUT_TABLES- input tables used by the endpoint (if any)OUTPUT_TABLE- output table created by the endpoint (if any)DEPENDENCIES- list of prior execution steps upon which this step depends
-
ANALYZE- same asPHYSICAL, including additional run-time details:RUN_TIME- execution time of each endpoint callRESULT_ROWS- number of records produced in the endpoint call
-
VERBOSE- same asPHYSICAL, including endpoint parameter details:COLUMNS- columns passed to the endpoint callEXPRESSIONS- expressions passed to the endpoint callOPTIONS- option keys & values passed to the endpoint callLAST_USE_TABLES- list of tables that will not be used by any following execution stepADDITIONAL_INFO- other parameters passed to the endpoint call
-
VERBOSE ANALYZE- same asVERBOSE&ANALYZEtogether, including the execution plan for any joins contained within the query -
FORMAT JSON- outputs the result in JSON format -
FORMAT TABLE- (default) outputs the result in tabular format
ANALYZE will cause the statement to be executed
in order to collect run-time statistics on the endpoint calls made.