Overview

Datafusion Functions

Since GreptimeDB's query engine is built based on Apache Arrow DataFusion, GreptimeDB inherits all built-in functions in DataFusion. These functions include:

• Aggregate functions: such as COUNT, SUM, MIN, MAX, etc. For a detailed list, please refer to Aggregate Functions
• Scalar functions: such as ABS, COS, FLOOR, etc. For a detailed list, please refer to Scalar Functions
• Window functions: performs a calculation across a set of table rows that are somehow related to the current row. For a detailed list, please refer to Window Functions

To find all the DataFusion functions, please refer to DataFusion Functions.

arrow_cast

arrow_cast function is from DataFusion's arrow_cast. It's illustrated as:

arrow_cast(expression, datatype)

Where the datatype can be any valid Arrow data type in this list. The four timestamp types are:

• Timestamp(Second, None)
• Timestamp(Millisecond, None)
• Timestamp(Microsecond, None)
• Timestamp(Nanosecond, None)

(Notice that the None means the timestamp is timezone naive)

GreptimeDB Functions

String Functions

DataFusion String Function.GreptimeDB provides:

• matches(expression, pattern) for full text search.

Math Functions

DataFusion Math Function.

GreptimeDB provides:

• clamp(value, lower, upper) to restrict a given value between a lower and upper bound:

SELECT CLAMP(10, 0, 1);

+------------------------------------+
| clamp(Int64(10),Int64(0),Int64(1)) |
+------------------------------------+
|                                  1 |
+------------------------------------+

SELECT CLAMP(0.5, 0, 1)

+---------------------------------------+
| clamp(Float64(0.5),Int64(0),Int64(1)) |
+---------------------------------------+
|                                   0.5 |
+---------------------------------------+

• mod(x, y) to get the remainder of a number divided by another number:

SELECT mod(18, 4);

+-------------------------+
| mod(Int64(18),Int64(4)) |
+-------------------------+
|                       2 |
+-------------------------+

• pow(x, y) to get the value of a number raised to the power of another number:

SELECT pow(2, 10);

+-------------------------+
| pow(Int64(2),Int64(10)) |
+-------------------------+
|                    1024 |
+-------------------------+

Date and Time Functions

DataFusion Time and Date Function. GreptimeDB provides:

• date_add(expression, interval) to add an interval value to Timestamp, Date, or DateTime

SELECT date_add('2023-12-06'::DATE, '3 month 5 day');

+----------------------------------------------------+
| date_add(Utf8("2023-12-06"),Utf8("3 month 5 day")) |
+----------------------------------------------------+
| 2024-03-11                                         |
+----------------------------------------------------+

• date_sub(expression, interval) to subtract an interval value to Timestamp, Date, or DateTime

SELECT date_sub('2023-12-06 07:39:46.222'::TIMESTAMP_MS, INTERVAL '5 day');

+-----------------------------------------------------------------------------------------------------------------------------------------+
| date_sub(arrow_cast(Utf8("2023-12-06 07:39:46.222"),Utf8("Timestamp(Millisecond, None)")),IntervalMonthDayNano("92233720368547758080")) |
+-----------------------------------------------------------------------------------------------------------------------------------------+
| 2023-12-01 07:39:46.222000                                                                                                              |
+-----------------------------------------------------------------------------------------------------------------------------------------+

• date_format(expression, fmt) to format Timestamp, Date, or DateTime into string by the format:

SELECT date_format('2023-12-06 07:39:46.222'::TIMESTAMP, '%Y-%m-%d %H:%M:%S:%3f');

+-----------------------------------------------------------------------------------------------------------------------------+
| date_format(arrow_cast(Utf8("2023-12-06 07:39:46.222"),Utf8("Timestamp(Millisecond, None)")),Utf8("%Y-%m-%d %H:%M:%S:%3f")) |
+-----------------------------------------------------------------------------------------------------------------------------+
| 2023-12-06 07:39:46:222                                                                                                     |
+-----------------------------------------------------------------------------------------------------------------------------+

Supported specifiers refer to the chrono::format::strftime module.

• to_unixtime(expression) to convert the expression into the Unix timestamp in seconds. The argument can be integers (Unix timestamp in milliseconds), Timestamp, Date, DateTime, or String. If the argument is the string type, the function will first try to convert it into a DateTime, Timestamp, or Date.

select to_unixtime('2023-03-01T06:35:02Z');

+-------------------------------------------+
| to_unixtime(Utf8("2023-03-01T06:35:02Z")) |
+-------------------------------------------+
|                                1677652502 |
+-------------------------------------------+

select to_unixtime('2023-03-01'::date);

+---------------------------------+
| to_unixtime(Utf8("2023-03-01")) |
+---------------------------------+
|                      1677628800 |
+---------------------------------+

• to_timezone(expression, timezone) to convert the expression by the timezone. The argument can be integers (Unix timestamp in milliseconds), Timestamp, or String. If the argument is the string type, the function will first try to convert it into a Timestamp.

SELECT to_timezone('2022-09-20T14:16:43.012345+08:00', 'Europe/Berlin');

+-----------------------------------------------------------------------------+
| to_timezone(Utf8("2022-09-20T14:16:43.012345+08:00"),Utf8("Europe/Berlin")) |
+-----------------------------------------------------------------------------+
| 2022-09-20 08:16:43.012345                                                  |
+-----------------------------------------------------------------------------+

SELECT to_timezone(1709992225000, 'Asia/Shanghai');

+---------------------------------------------------------+
| to_timezone(Int64(1709992225000),Utf8("Asia/Shanghai")) |
+---------------------------------------------------------+
| 2024-03-09 21:50:25                                     |
+---------------------------------------------------------+

• timezone() to retrieve the current session timezone:

select timezone();

+------------+
| timezone() |
+------------+
| UTC        |
+------------+

System Functions

• isnull(expression) to check whether an expression is NULL:

 SELECT isnull(1);
 
 +------------------+
| isnull(Int64(1)) |
+------------------+
|                0 |
+------------------+

SELECT isnull(NULL);

+--------------+
| isnull(NULL) |
+--------------+
|            1 |
+--------------+

• build() retrieves the GreptimeDB build info.
• version() retrieves the GreptimeDB version.
• database() retrieves the current session database:

select database();

+------------+
| database() |
+------------+
| public     |
+------------+

Admin Functions

GreptimeDB provides some administration functions to manage the database and data:

• flush_table(table_name) to flush a table's memtables into SST file by table name.
• flush_region(region_id) to flush a region's memtables into SST file by region id. Find the region id through PARTITIONS table.
• compact_table(table_name) to schedule a compaction task for a table by table name.
• compact_region(region_id) to schedule a compaction task for a region by region id.
• migrate_region(region_id, from_peer, to_peer, [timeout]) to migrate regions between datanodes, please read the Region Migration.
• procedure_state(procedure_id) to query a procedure state by its id.
• flush_flow(flow_name) to flush a flow's output into the sink table.

For example:

-- Flush the table test --
select flush_table("test");

-- Schedule a compaction for table test --
select compact_table("test");