Documentation Index
Fetch the complete documentation index at: https://private-7c7dfe99-page-updates.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Functions for working with UUIDs
UUIDv7 generation
The generated UUID contains a 48-bit timestamp in Unix milliseconds, followed by version “7” (4 bits), a counter (42 bits) to distinguish UUIDs within a millisecond (including a variant field “2”, 2 bits), and a random field (32 bits). For any given timestamp (unix_ts_ms), the counter starts at a random value and is incremented by 1 for each new UUID until the timestamp changes. In case the counter overflows, the timestamp field is incremented by 1 and the counter is reset to a random new start value.
The UUID generation functions guarantee that the counter field within a timestamp increments monotonically across all function invocations in concurrently running threads and queries.
Snowflake ID generation
The generated Snowflake ID contains the current Unix timestamp in milliseconds (41 + 1 top zero bits), followed by a machine id (10 bits), and a counter (12 bits) to distinguish IDs within a millisecond. For any given timestamp (unix_ts_ms), the counter starts at 0 and is incremented by 1 for each new Snowflake ID until the timestamp changes. In case the counter overflows, the timestamp field is incremented by 1 and the counter is reset to 0.
The generated Snowflake IDs are based on the UNIX epoch 1970-01-01. While no standard or recommendation exists for the epoch of Snowflake IDs, implementations in other systems may use a different epoch, e.g. Twitter/X (2010-11-04) or Mastodon (2015-01-01).
UUIDNumToString
Introduced in: v1.1.0 Takes a binary representation of a UUID, with its format optionally specified byvariant (Big-endian by default), and returns a string containing 36 characters in text format.
Syntax
binary— Binary representation of a UUID.FixedString(16)variant— Variant as specified by RFC4122. 1 =Big-endian(default), 2 =Microsoft.(U)Int*
String
Examples
Usage example
Query
Response
Query
Response
UUIDStringToNum
Introduced in: v1.1.0 Accepts a string containing 36 characters in the formatxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, and returns a FixedString(16) as its binary representation, with its format optionally specified by variant (Big-endian by default).
Syntax
string— A string or fixed-string of 36 characters)StringorFixedString(36)variant— Variant as specified by RFC4122. 1 =Big-endian(default), 2 =Microsoft.(U)Int*
string. FixedString(16)
Examples
Usage example
Query
Response
Query
Response
UUIDToNum
Introduced in: v24.5.0 Accepts a UUID and returns its binary representation as a FixedString(16), with its format optionally specified byvariant (Big-endian by default).
This function replaces calls to two separate functions UUIDStringToNum(toString(uuid)) so no intermediate conversion from UUID to string is required to extract bytes from a UUID.
Syntax
uuid— UUID.StringorFixedStringvariant— Variant as specified by RFC4122. 1 =Big-endian(default), 2 =Microsoft.(U)Int*
FixedString(16)
Examples
Usage example
Query
Response
Query
Response
UUIDv7ToDateTime
Introduced in: v24.5.0 Returns the timestamp component of a UUID version 7. Syntaxuuid— A UUID version 7.Stringtimezone— Optional. Timezone name for the returned value.String
1970-01-01 00:00:00.000. DateTime64(3)
Examples
Usage example
Query
Response
Query
Response
dateTime64ToSnowflake
Introduced in: v21.10.0 Converts a DateTime64 to the first Snowflake ID at the giving time. Syntaxvalue— Date with time.DateTime64
Int64
Examples
Usage example
Query
Response
dateTime64ToSnowflakeID
Introduced in: v24.6.0 Converts a DateTime64 value to the first Snowflake ID at the giving time. Syntaxvalue— Date with time.DateTime64epoch— Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657.UInt*
UInt64
Examples
simple
Query
Response
dateTimeToSnowflake
Introduced in: v21.10.0 Converts a DateTime value to the first Snowflake ID at the giving time. Syntaxvalue— Date with time.DateTime
Int64
Examples
Usage example
Query
Response
dateTimeToSnowflakeID
Introduced in: v24.6.0 Converts a DateTime value to the first Snowflake ID at the giving time. Syntaxvalue— Date with time.DateTimeepoch— Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657.UInt*
UInt64
Examples
simple
Query
Response
dateTimeToUUIDv7
Introduced in: v25.8.0 Converts a DateTime value to a UUIDv7 at the given time. See section “UUIDv7 generation” for details on UUID structure, counter management, and concurrency guarantees.As of September 2025, version 7 UUIDs are in draft status and their layout may change in future.
value— Date with time.DateTime
UUID
Examples
Usage example
Query
Response
Query
Response
generateSnowflakeID
Introduced in: v24.6.0 Generates a Snowflake ID. FunctiongenerateSnowflakeID guarantees that the counter field within a timestamp increments monotonically across all function invocations in concurrently running threads and queries.
See section “Snowflake ID generation” for implementation details.
Syntax
expr— An arbitrary expression used to bypass common subexpression elimination if the function is called multiple times in a query. The value of the expression has no effect on the returned Snowflake ID. Optional. -machine_id— A machine ID, the lowest 10 bits are used. Int64. Optional.
UInt64
Examples
Usage example
Query
Response
Query
Response
Query
Response
generateUUIDv4
Introduced in: v1.1.0 Generates a version 4 UUID. Syntaxexpr— Optional. An arbitrary expression used to bypass common subexpression elimination if the function is called multiple times in a query. The value of the expression has no effect on the returned UUID.
UUID
Examples
Usage example
Query
Response
Query
Response
generateUUIDv7
Introduced in: v24.5.0 Generates a version 7 UUID. See section “UUIDv7 generation” for details on UUID structure, counter management, and concurrency guarantees.As of September 2025, version 7 UUIDs are in draft status and their layout may change in future.
expr— Optional. An arbitrary expression used to bypass common subexpression elimination if the function is called multiple times in a query. The value of the expression has no effect on the returned UUID.Any
UUID
Examples
Usage example
Query
Response
Query
Response
snowflakeIDToDateTime
Introduced in: v24.6.0 Returns the timestamp component of a Snowflake ID as a value of type DateTime. Syntaxvalue— Snowflake ID.UInt64epoch— Optional. Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657.UInt*time_zone— Optional. Timezone. The function parsestime_stringaccording to the timezone.String
value. DateTime
Examples
Usage example
Query
Response
snowflakeIDToDateTime64
Introduced in: v24.6.0 Returns the timestamp component of a Snowflake ID as a value of type DateTime64. Syntaxvalue— Snowflake ID.UInt64epoch— Optional. Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657.UInt*time_zone— Optional. Timezone. The function parsestime_stringaccording to the timezone.String
value as a DateTime64 with scale = 3, i.e. millisecond precision. DateTime64
Examples
Usage example
Query
Response
snowflakeToDateTime
Introduced in: v21.10.0 Extracts the timestamp component of a Snowflake ID in DateTime format. Syntaxvalue— Snowflake ID.Int64time_zone— Optional. Timezone. The function parsestime_stringaccording to the timezone.String
value. DateTime
Examples
Usage example
Query
Response
snowflakeToDateTime64
Introduced in: v21.10.0 Extracts the timestamp component of a Snowflake ID in DateTime64 format. Syntaxvalue— Snowflake ID.Int64time_zone— Optional. Timezone. The function parsestime_stringaccording to the timezone.String
value. DateTime64(3)
Examples
Usage example
Query
Response
toUUIDOrDefault
Introduced in: v21.1.0 Converts a String value to UUID type. If the conversion fails, returns a default UUID value instead of throwing an error. This function attempts to parse a string of 36 characters in the standard UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). If the string cannot be converted to a valid UUID, the function returns the provided default UUID value. Syntaxstring— String of 36 characters or FixedString(36) to be converted to UUID. -default— UUID value to be returned if the first argument cannot be converted to UUID type.
UUID
Examples
Successful conversion returns the parsed UUID
Query
Response
Query
Response
toUUIDOrNull
Introduced in: v20.12.0 Converts an input value to a value of typeUUID but returns NULL in case of an error.
Like toUUID but returns NULL instead of throwing an exception on conversion errors.
Supported arguments:
- String representations of UUID in standard format (8-4-4-4-12 hexadecimal digits).
- String representations of UUID without hyphens (32 hexadecimal digits).
NULL):
- Invalid string formats.
- Non-string types.
- Malformed UUIDs.
x— A string representation of a UUID.String
NULL. UUID or NULL
Examples
Usage examples
Query
Response