SQL API reference
SQL API supports the following commands as well as functions and operators.
If you'd like to propose a function or an operator to be supported in the SQL API, check the existing issues on GitHub (opens in a new tab). If there are no relevant issues, please file a new one (opens in a new tab).
SQL commands
SELECT
Synopsis:
SELECT select_expr [, ...]
FROM from_item
CROSS JOIN join_item
ON join_criteria]*
[ WHERE where_condition ]
[ GROUP BY grouping_expression ]
[ HAVING having_expression ]
[ LIMIT number ] [ OFFSET number ];SELECT retrieves rows from a cube.
The FROM clause specifies one or more source cube tables for the SELECT.
Qualification conditions can be added (via WHERE) to restrict the returned
rows to a small subset of the original dataset.
Example:
SELECT COUNT(*), orders.status, users.city
FROM orders
CROSS JOIN users
WHERE city IN ('San Francisco', 'Los Angeles')
GROUP BY orders.status, users.city
HAVING status = 'shipped'
LIMIT 1 OFFSET 1;EXPLAIN
Synopsis:
EXPLAIN [ ANALYZE ] statementThe EXPLAIN command displays the query execution plan that the Cube planner
will generate for the supplied statement.
The ANALYZE will execute statement and display actual runtime statistics,
including the total elapsed time expended within each plan node and the total
number of rows it actually returned.
Example:
EXPLAIN WITH cte AS (
SELECT o.count as count, p.name as product_name, p.description as product_description
FROM orders o
CROSS JOIN products p
)
SELECT COUNT(*) FROM cte;
plan_type | plan
---------------+---------------------------------------------------------------------
logical_plan | Projection: #COUNT(UInt8(1)) +
| Aggregate: groupBy=[[]], aggr=[[COUNT(UInt8(1))]] +
| CubeScan: request={ +
| "measures": [ +
| "orders.count" +
| ], +
| "dimensions": [ +
| "products.name", +
| "products.description" +
| ], +
| "segments": [] +
| }
physical_plan | ProjectionExec: expr=[COUNT(UInt8(1))@0 as COUNT(UInt8(1))] +
| HashAggregateExec: mode=Final, gby=[], aggr=[COUNT(UInt8(1))] +
| HashAggregateExec: mode=Partial, gby=[], aggr=[COUNT(UInt8(1))]+
| CubeScanExecutionPlan +
|
(2 rows)With ANALYZE:
EXPLAIN ANALYZE WITH cte AS (
SELECT o.count as count, p.name as product_name, p.description as product_description
FROM orders o
CROSS JOIN products p
)
SELECT COUNT(*) FROM cte;
plan_type | plan
-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------
Plan with Metrics | ProjectionExec: expr=[COUNT(UInt8(1))@0 as COUNT(UInt8(1))], metrics=[output_rows=1, elapsed_compute=541ns, spill_count=0, spilled_bytes=0, mem_used=0] +
| HashAggregateExec: mode=Final, gby=[], aggr=[COUNT(UInt8(1))], metrics=[output_rows=1, elapsed_compute=6.583µs, spill_count=0, spilled_bytes=0, mem_used=0] +
| HashAggregateExec: mode=Partial, gby=[], aggr=[COUNT(UInt8(1))], metrics=[output_rows=1, elapsed_compute=13.958µs, spill_count=0, spilled_bytes=0, mem_used=0]+
| CubeScanExecutionPlan, metrics=[] +
|
(1 row)SHOW
Synopsis:
SHOW name
SHOW ALLReturns the value of a runtime parameter using name, or all runtime parameters
if ALL is specified.
Example:
SHOW timezone;
setting
---------
GMT
(1 row)
SHOW ALL;
name | setting | description
-----------------------------+----------------+-------------
max_index_keys | 32 |
max_allowed_packet | 67108864 |
timezone | GMT |
client_min_messages | NOTICE |
standard_conforming_strings | on |
extra_float_digits | 1 |
transaction_isolation | read committed |
application_name | NULL |
lc_collate | en_US.utf8 |
(9 rows)SQL functions and operators
SQL API currently implements a subset of functions and operators supported by PostgreSQL (opens in a new tab). Additionally, it supports a few custom functions.
Comparison operators
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
< | Returns TRUE if the first value is less than the second | ✅ Yes | |
> | Returns TRUE if the first value is greater than the second | ✅ Yes | |
<= | Returns TRUE if the first value is less than or equal to the second | ✅ Yes | |
>= | Returns TRUE if the first value is greater than or equal to the second | ✅ Yes | |
= | Returns TRUE if the first value is equal to the second | ✅ Yes | |
<> or != | Returns TRUE if the first value is not equal to the second | ✅ Yes |
Comparison predicates
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
BETWEEN | Returns TRUE if the first value is between the second and the third | ❌ No | |
IS NULL | Test whether value is NULL | ✅ Yes | |
IS NOT NULL | Test whether value is not NULL | ✅ Yes |
Mathematical functions
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
ABS | Absolute value | ✅ Yes | |
CEIL | Nearest integer greater than or equal to argument | ✅ Yes | |
DEGREES | Converts radians to degrees | ✅ Yes | |
EXP | Exponential (e raised to the given power) | ✅ Yes | |
FLOOR | Nearest integer less than or equal to argument | ✅ Yes | |
LN | Natural logarithm | ✅ Yes | |
LOG | Base 10 logarithm | ✅ Yes | |
LOG10 | Base 10 logarithm (same as LOG) | ✅ Yes | |
PI | Approximate value of π | ✅ Yes | |
POWER | a raised to the power of b | ✅ Yes | |
RADIANS | Converts degrees to radians | ✅ Yes | |
ROUND | Rounds v to s decimal places | ✅ Yes | |
SIGN | Sign of the argument (-1, 0, or +1) | ✅ Yes | |
SQRT | Square root | ✅ Yes | |
TRUNC | Truncates to integer (towards zero) | ✅ Yes |
Trigonometric functions
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
ACOS | Inverse cosine, result in radians | ✅ Yes | |
ASIN | Inverse sine, result in radians | ✅ Yes | |
ATAN | Inverse tangent, result in radians | ✅ Yes | |
ATAN2 | Inverse tangent of y/x, result in radians | ✅ Yes | |
COS | Cosine, argument in radians | ✅ Yes | |
COT | Cotangent, argument in radians | ✅ Yes | |
SIN | Sine, argument in radians | ✅ Yes | |
TAN | Tangent, argument in radians | ✅ Yes |
String functions and operators
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
|| | Concatenates two strings | ✅ Yes | |
BTRIM | Removes the longest string containing only characters in characters from the start and end of string | ✅ Yes | |
BIT_LENGTH | Returns number of bits in the string (8 times the OCTET_LENGTH) | ✅ Yes | |
CHAR_LENGTH or CHARACTER_LENGTH | Returns number of characters in the string | ✅ Yes | |
LOWER | Converts the string to all lower case | ✅ Yes | |
LTRIM | Removes the longest string containing only characters in characters from the start of string | ✅ Yes | |
OCTET_LENGTH | Returns number of bytes in the string | ✅ Yes | |
POSITION | Returns first starting index of the specified substring within string, or zero if it's not present | ✅ Yes | |
RTRIM | Removes the longest string containing only characters in characters from the end of string | ✅ Yes | |
SUBSTRING | Extracts the substring of string | ✅ Yes | |
TRIM | Removes the longest string containing only characters in characters from the start, end, or both ends of string | ✅ Yes | |
UPPER | Converts the string to all upper case | ✅ Yes |
Other string functions
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
ASCII | Returns the numeric code of the first character of the argument | ✅ Yes | |
CONCAT | Concatenates the text representations of all the arguments | ✅ Yes | |
LEFT | Returns first n characters in the string, or when n is negative, returns all but last ABS(n) characters | ✅ Yes | |
REPEAT | Repeats string the specified number of times | ✅ Yes | |
REPLACE | Replaces all occurrences in string of substring from with substring to | ✅ Yes | |
RIGHT | Returns last n characters in the string, or when n is negative, returns all but first ABS(n) characters | ✅ Yes | |
STARTS_WITH | Returns TRUE if string starts with prefix | ✅ Yes |
Pattern matching
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
LIKE | Returns TRUE if the string matches the supplied pattern | ✅ Yes | |
REGEXP_SUBSTR | Returns the substring that matches a POSIX regular expression pattern | ✅ Yes |
Data type formatting functions
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
TO_CHAR | Converts a timestamp to string according to the given format | ✅ Yes |
Date/time functions
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
DATE_ADD | Add an interval to a timestamp with time zone | ✅ Yes | |
DATE_TRUNC | Truncate a timestamp to specified precision | ✅ Yes | |
DATEDIFF | From Redshift (opens in a new tab). Returns the difference between the date parts of two date or time expressions | ✅ Yes | |
EXTRACT | Retrieves subfields such as year or hour from date/time values | ✅ Yes | |
LOCALTIMESTAMP | Returns the current date and time without time zone | ✅ Yes | |
NOW | Returns the current date and time with time zone | ✅ Yes |
Conditional expressions
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function, expression | Description | Pushdown | |
|---|---|---|---|
CASE | Generic conditional expression | ✅ Yes | |
COALESCE | Returns the first of its arguments that is not NULL | ✅ Yes | |
NULLIF | Returns NULL if both arguments are equal, otherwise returns the first argument | ✅ Yes | |
GREATEST | Select the largest value from a list of expressions | ✅ Yes | |
LEAST | Select the smallest value from a list of expressions | ✅ Yes |
General-purpose aggregate functions
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
AVG | Computes the average (arithmetic mean) of all the non-NULL input values | ✅ Yes | |
COUNT | Computes the number of input rows in which the input value is not NULL | ✅ Yes | |
COUNT(DISTINCT) | Computes the number of input rows containing unique input values | ✅ Yes | |
MAX | Computes the maximum of the non-NULL input values | ✅ Yes | |
MIN | Computes the minimum of the non-NULL input values | ✅ Yes | |
SUM | Computes the sum of the non-NULL input values | ✅ Yes | |
MEASURE | Works with measures of any type | ✅ Yes |
In projections in inner parts of post-processing queries:
AVG,COUNT,MAX,MIN, andSUMcan only be used with measures of compatible types.- If
COUNT(*)is specified, Cube will query the first measure of typecountof the relevant cube.
Aggregate functions for statistics
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
COVAR_POP | Computes the population covariance | ✅ Yes | |
COVAR_SAMP | Computes the sample covariance | ✅ Yes | |
STDDEV_POP | Computes the population standard deviation of the input values | ✅ Yes | |
STDDEV_SAMP | Computes the sample standard deviation of the input values | ✅ Yes | |
VAR_POP | Computes the population variance of the input values | ✅ Yes | |
VAR_SAMP | Computes the sample variance of the input values | ✅ Yes |
Row and array comparisons
Learn more in the relevant section (opens in a new tab) of the PostgreSQL documentation.
| Function | Description | Pushdown | |
|---|---|---|---|
IN | Returns TRUE if a left-side value matches any of right-side values | ✅ Yes | |
NOT IN | Returns TRUE if a left-side value matches none of right-side values | ✅ Yes |
Custom functions
| Function | Description |
|---|---|
XIRR | Calculates the internal rate of return (opens in a new tab) for a series of cash flows |
See the XIRR recipe for more details.